ACP 代理

代理客户端协议（ACP） 会话�?OpenClaw 可以通过 ACP 后端插件运行外部编码 harness（例�?Pi、Claude Code、Codex、OpenCode �?Gemini CLI）�?

如果你用自然语言请求 OpenClaw ”�?Codex 中运行这�?�?在线程中启动 Claude Code”，OpenClaw 应该将该请求路由�?ACP 运行时（而不是原生子代理运行时）�?

快速操作流�?

当你想要一个实用的 /acp 运行手册时使用：

1. 创建会话�?
   • /acp spawn codex --mode persistent --thread auto
2. 在绑定的线程中工作（或显式指定该会话密钥）�?
3. 检查运行时状态：
   • /acp status
4. 根据需要调整运行时选项�?
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. 推动活跃会话而不替换上下文：
   • /acp steer tighten logging and continue
6. 停止工作�?
   • /acp cancel（停止当前轮次），或
   • /acp close（关闭会�?+ 移除绑定�?

人类快速入�?

自然请求的示例：

• “在这里的线程中启动一个持久的 Codex 会话并保持专注�?
• “作为一次�?Claude Code ACP 会话运行这个并总结结果�?
• “为此任务使用 Gemini CLI 在线程中运行，然后在同一线程中保持后续对话�?

OpenClaw 应该做的�?

1. 选择 runtime: "acp"�?
2. 解析请求�?harness 目标（例�?agentId �?codex）�?
3. 如果请求线程绑定且当前频道支持，�?ACP 会话绑定到该线程�?
4. 将后续线程消息路由到同一�?ACP 会话，直到取消聚�?关闭/过期�?

ACP 与子代理

当你想要外部 harness 运行时使�?ACP。当你想�?OpenClaw 原生委托运行时使用子代理�?

另见子代理�?

线程绑定会话（频道无关）

当频道适配器启用了线程绑定时，ACP 会话可以绑定到线程：

• OpenClaw 将线程绑定到目标 ACP 会话�?
• 该线程中的后续消息路由到绑定�?ACP 会话�?
• ACP 输出传回同一线程�?
• 取消聚焦/关闭/归档/TTL 过期移除绑定�?

线程绑定支持因适配器而异。如果当前频道适配器不支持线程绑定，OpenClaw 返回清晰的不支持/不可用消息�?

线程绑定 ACP 所需的功能标志：

• acp.enabled=true
• acp.dispatch.enabled=true
• 频道适配�?ACP 线程生成标志启用（因适配器而异�?
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true

支持线程的频�?

• 任何公开会话/线程绑定功能的频道适配器�?
• 当前内置支持：Discord�?
• 插件频道可以通过相同的绑定接口添加支持�?

启动 ACP 会话（接口）

�?sessions_spawn

使用 runtime: "acp" 从代理轮次或工具调用启动 ACP 会话�?

{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

注意�?

• runtime 默认�?subagent，所以对 ACP 会话要显式设�?runtime: "acp"�?
• 如果省略 agentId，OpenClaw 在配置时使用 acp.defaultAgent�?
• mode: "session" 需�?thread: true 来保持持久的绑定对话�?

接口详情�?

• task（必需）：发送到 ACP 会话的初始提示�?
• runtime（ACP 必需）：必须�?"acp"�?
• agentId（可选）：ACP 目标 harness id。如已设置，回退�?acp.defaultAgent�?
• thread（可选，默认�?false）：在支持的地方请求线程绑定流程�?
• mode（可选）：run（一次性）�?session（持久）�?
  • 默认�?run
  • 如果 thread: true 且模式省略，OpenClaw 可能会根据运行时路径默认为持久行�?
  • mode: "session" 需�?thread: true
• cwd（可选）：请求的运行时工作目录（由后�?运行时策略验证）�?
• label（可选）：面向操作员的标签，用于会话/横幅文本�?

�?/acp 命令

需要时使用 /acp spawn 进行显式的操作员控制�?

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --thread here

关键标志�?

• --mode persistent|oneshot
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

见斜杠命令�?

会话目标解析

大多�?/acp 操作接受可选的会话目标（session-key、session-id �?session-label）�?

解析顺序�?

1. 显式目标参数（或 /acp steer �?--session�?
   • 尝试密钥
   • 然后 UUID 形状的会�?id
   • 然后标签
2. 当前线程绑定（如果此对话/线程绑定�?ACP 会话�?
3. 当前请求者会话回退

如果没有目标解析，OpenClaw 返回清晰错误（Unable to resolve session target: ...）�?

生成线程模式

/acp spawn 支持 --thread auto|here|off�?

注意�?

• 在非线程绑定界面，默认行为实际上等同�?off�?
• 线程绑定生成需要频道策略支持（对于 Discord：channels.discord.threadBindings.spawnAcpSessions=true）�?

ACP 控制

可用命令系列�?

• /acp spawn
• /acp cancel
• /acp steer
• /acp close
• /acp status
• /acp set-mode
• /acp set
• /acp cwd
• /acp permissions
• /acp timeout
• /acp model
• /acp reset-options
• /acp sessions
• /acp doctor
• /acp install

/acp status 显示有效的运行时选项，以及（当可用时）运行时级和后端级会话标识符�?

某些控制依赖于后端能力。如果后端不支持某控制，OpenClaw 返回清晰的不支持控制错误�?

ACP 命令手册

运行时选项映射

/acp 有便捷命令和通用设置器�?

等效操作�?

• /acp model <id> 映射到运行时配置�?model�?
• /acp permissions <profile> 映射到运行时配置�?approval_policy�?
• /acp timeout <seconds> 映射到运行时配置�?timeout�?
• /acp cwd <path> 直接更新运行�?cwd 覆盖�?
• /acp set <key <value>> 是通用路径�?
  • 特殊案例：key=cwd 使用 cwd 覆盖路径�?
• /acp reset-options 清除目标会话的所有运行时覆盖�?

acpx harness 支持（当前）

当前 acpx 内置 harness 别名�?

• pi
• claude
• codex
• opencode
• gemini

�?OpenClaw 使用 acpx 后端时，优先使用这些 agentId 值，除非你的 acpx 配置定义了自定义代理别名�?

直接 acpx CLI 使用也可以通过 --agent <command> 定位任意适配器，但那个原始的逃生舱是 acpx CLI 功能（不是正常的 OpenClaw agentId 路径）�?

所需配置

核心 ACP 基线�?

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

线程绑定配置因频道适配器而异。Discord 示例�?

{
  session: {
    threadBindings: {
      enabled: true,
      ttlHours: 24,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

如果线程绑定 ACP 生成不起作用，首先验证适配器功能标志：

• Discord: channels.discord.threadBindings.spawnAcpSessions=true

见配置参考�?

acpx 后端的插件设�?

安装并启用插件：

openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true

开发期间本地工作区安装�?

openclaw plugins install ./extensions/acpx

然后验证后端健康�?

/acp doctor

固定�?acpx 安装策略（当前行为）

@openclaw/acpx 现在执行严格的插件本地固定模型：

1. 扩展�?extensions/acpx/package.json 中固定精确的 acpx 依赖�?
2. 运行时命令固定到插件本地二进制文件（extensions/acpx/node_modules/.bin/acpx），而不是全局 PATH�?
3. 插件配置不暴�?command �?commandArgs，因此阻止运行时命令漂移�?
4. 启动时立即将 ACP 后端注册为未就绪�?
5. 后台确保作业验证 acpx --version 与固定版本�?
6. 如果缺失/不匹配，它运行插件本地安装（npm install --omit=dev --no-save acpx@<pinned>）并在健康前重新验证�?

注意�?

• OpenClaw 启动保持非阻塞，同时 acpx 确保运行�?
• 如果网络/安装失败，后端保持不可用，/acp doctor 报告可操作的修复�?

见插件�?

故障排除