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,技术栈为:
- OpenClaw ACP 会话控制平面。
- 官方
@openclaw/acpx运行时插件。 - Claude ACP 适配器。
- 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
这样的现有链接仍然可以解析。每个条目都指向现在承载该内容的页面。
- 开箱即用吗?
- 首次运行注意事项
- 运行时前提条件
- 支持的运行框架目标
- 运维手册
- 生成
- 工作
- 检查状态
- 调优
- 引导
- 停止
- 生命周期详情
- 原生 Codex 路由规则
- 模型 / 提供商 / 运行时选择速查表
- ACP 路由自然语言触发器
- 绑定会话
- 心智模型
- 当前对话绑定
- 绑定规则与排他性
- 线程绑定会话
- 支持线程的频道
- 持久频道绑定
- 绑定模型
bindings[].typebindings[].matchbindings[].agentIdbindings[].acp.modebindings[].acp.labelbindings[].acp.cwdbindings[].acp.backend- 每个智能体的运行时默认值
- 示例
- 行为
- 启动 ACP 会话
- 来自
sessions_spawn - 来自
/acp命令 sessions_spawn参数taskruntimeagentIdthreadmodecwdlabelresumeSessionIdstreamTomodelthinking- 生成绑定与线程模式
--bind here|off--thread auto|here|off- 交付模型
- 交互式 ACP 会话
- 父级拥有的一次性 ACP 会话
sessions_send与 A2A 交付- 恢复现有会话
- 部署后冒烟测试
- 沙箱兼容性
- 会话目标解析
- 会话所有者与运行框架
- ACP 控制
- 运行时选项映射
- 故障排查
相关¶
- ACP 智能体 - 设置
- 智能体绑定
- 智能体发送
- CLI 后端
- Codex 测试框架
- Codex 测试框架运行时
- 多智能体沙箱工具
openclaw acp(桥接模式)- 子智能体
- 转向 — 活动运行转向和排队的 ACP 后续操作
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw