跳转至

ACP 代理

Agent Client Protocol (ACP) 会话允许 OpenClaw 通过 ACP 后端插件运行外部编码框架(Claude Code、Cursor、Copilot、Droid、 OpenClaw ACP、OpenCode、Gemini CLI 以及其他受支持的 acpx 框架)。 ACP 运行时负责每个会话及其取消操作。

Note

ACP 是外部框架路径,而不是默认的 Codex 路径。 原生 Codex app-server 插件负责 /codex ... 控制以及代理轮次中默认的 openai/gpt-* 嵌入式运行时。ACP 负责 /acp ... 控制 和 sessions_spawn({ runtime: "acp" }) 会话。

要让 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到 现有的 OpenClaw 频道对话,请使用 openclaw mcp serve,而不是 ACP。

我想看哪个页面?

你想... 使用此 备注
在当前对话中绑定或控制 Codex /codex bind、/codex threads 启用 codex 插件时的原生 Codex app-server 路径:绑定聊天回复、图像转发、model/fast/permissions、stop 和 steer。ACP 是显式回退
运行 Claude Code、Gemini CLI、显式 Codex ACP 或其他外部框架 经由 OpenClaw 本页 聊天绑定会话、/acp spawn、sessions_spawn({ runtime: "acp" })、后台任务、运行时控制
将 OpenClaw Gateway 会话 作为 ACP 服务器暴露给编辑器或客户端 openclaw acp 桥接模式:IDE/客户端通过 stdio/WebSocket 与 OpenClaw 进行 ACP 通信
使用本地 AI CLI(例如 Claude Code)作为代理的模型运行时 CLI 后端 非 ACP:仅通过 MCP 桥接使用 Gateway 工具,无 ACP 控制,无框架运行时

ACP 代理文档页面

本页是索引。ACP 代理的文档分布在七个页面,每个读者任务对应一个页面。 打开与你任务匹配的页面。

页面 何时阅读
ACP 代理快速入门 你正在安装 ACP 运行时插件或选择框架目标 id。
ACP 代理操作员运行手册 你从聊天中运行 /acp,并需要流程、生命周期和路由规则。
ACP 代理绑定 你正在绑定对话、线程或已配置的 bindings[] 条目。
ACP 代理会话 你需要 sessions_spawn 参数或 --bind 和 --thread 模式。
ACP 代理交付模型 你正在调试完成交付、恢复或沙箱边界。
ACP 代理控制 你需要 /acp 命令参考和运行时选项映射。
ACP 代理故障排查 你遇到 ACP 错误消息,并需要可能的原因和修复方法。

ACP 与子代理

当你想要外部框架运行时,使用 ACP。当启用 codex 插件时,使用 原生 Codex app-server 进行 Codex 对话绑定/控制。当你想要 OpenClaw 原生委托运行时,使用 子代理。

领域 ACP 会话 子代理运行
运行时 ACP 后端插件(例如 acpx) OpenClaw 原生子代理运行时
会话键 agent:<agentId>:acp:<uuid> agent:<agentId>:subagent:<uuid>
主命令 /acp ... /subagents ...
生成工具 带 runtime:"acp" 的 sessions_spawn sessions_spawn(默认运行时)

另请参阅 子代理。

ACP 如何运行 Claude Code

对于通过 ACP 运行的 Claude Code,技术栈为:

  1. OpenClaw ACP 会话控制平面。
  2. 官方 @openclaw/acpx 运行时插件。
  3. Claude ACP 适配器。
  4. Claude 侧运行时/会话机制。

ACP Claude 是一个 框架会话,具有 ACP 控制、会话恢复、 后台任务跟踪以及可选的对话/线程绑定。

CLI 后端是另一条路径:本地 CLI 作为模型运行时运行常规代理轮次, 没有 ACP 控制。请参阅 CLI 后端。

对于操作员,实用规则是:

  • 想要 /acp spawn、可绑定会话、运行时控制或持久化框架工作? 使用 ACP。
  • 想要常规代理轮次通过本地 CLI(例如 Claude Code)运行? 使用 CLI 后端。

acpx 框架、插件设置和权限

关于 acpx 框架配置(Claude Code / Codex / Gemini CLI 别名)、 plugin-tools 和 OpenClaw-tools MCP 桥接以及 ACP 权限模式, 请参阅 ACP 代理 - 设置。

各章节迁移位置

来自之前单页版本的每个章节标题 都在这里保留其锚点,因此像 /tools/acp-agents#persistent-channel-bindings 这样的现有链接仍然可以解析。每个条目都指向现在承载该内容的页面。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw