运行与 OpenClaw Gateway 通信的 Agent Client Protocol (ACP) 桥接器¶
openclaw acp 通过 stdio 与 IDE 进行 ACP 通信,并通过 WebSocket 将提示词转发给 Gateway,同时保持 ACP 会话与 Gateway 会话键的映射。它是基于 Gateway 的 ACP 桥接器,而不是完整的 ACP 原生编辑器运行时:它专注于会话路由、提示词交付和流式更新。
如果你希望外部 MCP 客户端直接与 OpenClaw 频道对话进行交流,而不是托管 ACP harness 会话,请改用 openclaw mcp serve。
它不是什么¶
openclaw acp 表示 OpenClaw 充当 ACP 服务器:IDE 或 ACP 客户端连接到 OpenClaw,OpenClaw 将该工作转发到 Gateway 会话中。
这与 ACP Agents 不同,后者通过 acpx 运行外部 harness,例如 Codex 或 Claude Code。
快速规则:
- 编辑器/客户端希望与 OpenClaw 进行 ACP 通信:使用
openclaw acp - OpenClaw 应将 Codex/Claude/Gemini 作为 ACP harness 启动:使用
/acp spawn和 ACP Agents
兼容性矩阵¶
| ACP 领域 | 状态 | 备注 |
|---|---|---|
initialize、newSession、prompt、cancel |
已实现 | 通过 stdio 到 Gateway chat/send + abort 的核心桥接流程。 |
listSessions、斜杠命令 |
已实现 | 会话列表基于 Gateway 会话状态工作,支持有界游标分页和 cwd 过滤(当 Gateway 会话行携带工作区元数据时);命令通过 available_commands_update 通告。 |
| 会话谱系元数据 | 已实现 | 会话列表和会话信息快照在 _meta 中包含 OpenClaw 的父级和子级谱系,以便 ACP 客户端无需私有 Gateway 侧信道即可渲染子代理图。 |
resumeSession、closeSession |
已实现 | Resume 将 ACP 会话重新绑定到现有 Gateway 会话,且不重放历史。Close 会取消活动中的桥接工作,将待处理提示词解析为已取消,并释放桥接会话状态。 |
loadSession |
部分 | 将 ACP 会话重新绑定到 Gateway 会话键,并为桥接创建的会话重放 ACP 事件账本历史。较旧/无账本的会话回退到已存储的用户/助手文本。 |
提示词内容(text、嵌入的 resource、图像) |
部分 | 文本/资源会扁平化为聊天输入;图像则成为 Gateway 附件。 |
| 会话模式 | 部分 | 支持 session/set_mode;桥接器暴露了基于 Gateway 的会话控制,用于思维层级、工具详细程度、推理、用量详情和提权操作。更广泛的 ACP 原生模式/配置表面仍不在范围内。 |
| 思维流式传输 | 已实现 | 模型思考内容以 agent_thought_chunk 会话更新形式流式传输。不会发出 ACP 原生会话计划。 |
| 会话信息和用量更新 | 部分 | 桥接器从缓存的 Gateway 会话快照发出 session_info_update 和尽力而为的 usage_update 通知。用量是近似值,并且仅在 Gateway 令牌总数标记为最新时发送。 |
| 工具流式传输 | 部分 | 当 Gateway 工具参数/结果暴露时,tool_call/tool_call_update 事件包含原始 I/O、文本内容和尽力而为的文件位置。不暴露嵌入式终端和更丰富的 diff 原生输出。 |
| 执行审批 | 部分 | 在活动 ACP 提示词轮次期间,Gateway 执行审批提示会通过 session/request_permission 转发给 ACP 客户端。 |
每会话 MCP 服务器(mcpServers) |
不支持 | 桥接模式拒绝每会话 MCP 服务器请求。请改为在 OpenClaw Gateway 或代理上配置 MCP。 |
客户端文件系统方法(fs/read_text_file、fs/write_text_file) |
不支持 | 桥接器不会调用 ACP 客户端文件系统方法。 |
客户端终端方法(terminal/*) |
不支持 | 桥接器不会创建 ACP 客户端终端,也不会通过工具调用流式传输终端 id。 |
| ACP 区域 | 状态 | 备注 |
|---|---|---|
助手旁白会以 agent_message_chunk 更新的形式出现在相关工具调用之前。当 Gateway 将流式文本重新分类为评论时,桥接会仅保留一次该旁白,并单独跟踪最终答案,因此工具使用不会截断答案或重放旁白。
已知限制¶
loadSession仅对由桥接创建的会话重放完整的 ACP 事件账本历史。旧会话/无账本会话使用转录回退,并且不会重建历史工具调用或系统通知。重放历史受会话、事件和保留内容限制约束;默认字节预算为 16 MiB 的 UTF-8 文本加上行开销。被截断的历史也使用转录回退。参见 ACP 重放核算。- 如果多个 ACP 客户端共享同一个 Gateway 会话键,事件和取消路由是尽力而为的,而不是按客户端严格隔离。当需要干净的编辑器本地轮次时,请优先使用默认隔离的
acp-bridge:<uuid>会话。 - Gateway 停止状态会转换为 ACP 停止原因,但该映射的表达力不如完全 ACP 原生运行时。
- 会话控件呈现一组聚焦的 Gateway 参数子集:思考级别、工具详细程度、推理、用量详情和提权操作。模型选择和 exec-host 控件不作为 ACP 配置选项暴露。
session_info_update和usage_update派生自 Gateway 会话快照,而不是实时 ACP 原生运行时核算。用量是近似值,不包含成本数据,并且仅在 Gateway 将总 token 数据标记为最新时发出。- 工具跟随数据是尽力而为的:桥接会呈现出现在已知工具参数/结果中的文件路径,但不会发出 ACP 终端或结构化文件差异。
- 执行审批中继的范围限定为当前活动的 ACP Prompt 轮次;来自其他 Gateway 会话的审批会被忽略。
用法¶
openclaw acp
# Remote Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>
# Remote Gateway (token from file)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# Attach to an existing session key
openclaw acp --session agent:main:main
# Attach by label (must already exist)
openclaw acp --session-label "support inbox"
# Reset the session key before the first prompt
openclaw acp --session agent:main:main --reset-session
ACP 客户端(调试)¶
使用内置 ACP 客户端,无需 IDE 即可对桥接进行健全性检查。它会启动 ACP 桥接,并允许你交互式地输入 Prompt。
会话建立后,意外的服务器信号退出会使客户端以状态 1 退出。当通过信号停止服务器时,显式 exit 或 quit 仍保持成功。数字服务器退出码会被传播,包括显式退出期间返回的非零退出码。关闭交互式输入(包括在空 Prompt 处按 Ctrl-D)使用相同的客户端拥有的关闭路径;它不会等待进行中的响应完成。
openclaw acp client
# Point the spawned bridge at a remote Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# Override the server command (default: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001
权限模型(客户端调试模式):
- 自动审批基于允许列表,并且仅适用于受信任的核心工具 ID。
read自动审批的范围限定为当前工作目录(设置--cwd时)。- ACP 仅自动审批狭窄的只读类别:活动 cwd 下范围限定的
read调用,以及只读搜索工具(search、web_search、memory_search)。未知/非核心工具、超出范围的读取、具备执行能力的工具、控制平面工具、变更工具和交互式流程始终需要显式 Prompt 审批。 - 服务器提供的
toolCall.kind被视为不可信元数据,而不是授权来源。 - 此 ACP 桥接策略独立于 ACPX 测试框架权限。如果你通过
acpx后端运行 OpenClaw,则plugins.entries.acpx.config.permissionMode=approve-all是该测试框架会话的紧急“yolo”开关。
协议冒烟测试¶
对于协议级调试,请启动具有隔离状态的 Gateway,并使用 ACP JSON-RPC 客户端通过 stdio 驱动 openclaw acp。覆盖 initialize、session/new、带有绝对 cwd 的 session/list、session/resume、session/close、重复关闭以及缺失恢复。
证明应包含已宣告的生命周期能力、由 Gateway 支持的会话行、更新通知以及 Gateway sessions.list 日志:
{
"initialize": {
"protocolVersion": 1,
"agentCapabilities": {
"sessionCapabilities": {
"list": {},
"resume": {},
"close": {}
}
}
},
"listSessions": {
"sessions": [
{
"sessionId": "agent:main:acp-smoke",
"cwd": "/path/to/workspace",
"_meta": {
"sessionKey": "agent:main:acp-smoke",
"kind": "direct"
}
}
],
"nextCursor": null
},
"notifications": ["session_info_update", "available_commands_update", "usage_update"],
"gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]
}
避免仅使用 openclaw gateway call sessions.list 作为 ACP 证明。该 CLI 路径可能会请求新 token 操作员范围升级;ACP 桥接的正确性由 ACP stdio 帧加上 Gateway sessions.list 日志证明。
如何使用¶
当 IDE(或其他客户端)支持 Agent Client Protocol,并且你希望它驱动一个 OpenClaw Gateway 会话时,使用 ACP。
- 确保 Gateway 正在运行(本地或远程)。
- 配置 Gateway 目标(配置或标志)。
- 让 IDE 通过 stdio 运行
openclaw acp。
示例配置(持久化):
openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>
示例直接运行(不写入配置):
openclaw acp --url wss://gateway-host:18789 --token <token>
# preferred for local process safety
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
选择代理¶
ACP 不会直接选择代理。它根据 Gateway 会话键进行路由。使用代理作用域的会话键来指定某个特定代理:
openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123
每个 ACP 会话映射到单个 Gateway 会话键。一个代理可以拥有多个会话;除非你覆盖键或标签,否则 ACP 默认使用隔离的 acp-bridge:<uuid> 会话。
桥接模式不支持按会话的 mcpServers。如果 ACP 客户端在 newSession 或 loadSession 期间发送它们,桥接会返回明确错误,而不是静默忽略。
如果你希望 ACPX 支持的会话能够看到 OpenClaw 插件工具或选定的内置工具(例如 cron),请启用 Gateway 侧的 ACPX MCP 桥接,而不是尝试传递按会话的 mcpServers。参见 ACP 代理 和 OpenClaw 工具 MCP 桥接。
从 acpx 使用(Codex、Claude、其他 ACP 客户端)¶
如果你希望 Codex 或 Claude Code 等编码代理通过 ACP 与你的 OpenClaw bot 通信,请使用 acpx 及其内置的 openclaw 目标。
这里的 acpx 是来自 npm 的独立 acpx CLI,安装在运行编码代理的机器上。它与 ACP 代理 中描述的 @openclaw/acpx OpenClaw 插件不是同一事物;后者将 ACP 运行时嵌入 Gateway,并且不会安装 acpx 二进制文件。
典型流程:
- 在编码代理的机器上安装
acpxCLI 并运行 Gateway,确保 ACP 桥接能够访问它。 - 将
acpx openclaw指向openclaw acp。 - 指定你希望编码代理使用的 OpenClaw 会话键。
示例:
# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."
# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
"Ask my OpenClaw work agent for recent context relevant to this repo."
如果你希望 acpx openclaw 每次都指向特定的 Gateway 和会话键,请在 ~/.acpx/config.json 中覆盖 openclaw 代理命令:
```json validate=false { "agents": { "openclaw": { "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main" } } }
对于仓库本地的 OpenClaw checkout,请使用直接 CLI 入口点而不是开发运行器,以便 ACP 流保持干净:
```bash
env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
这是让 Codex、Claude Code 或其他支持 ACP 的客户端从 OpenClaw 代理获取上下文信息的最简单方式,而无需抓取终端。
Zed 编辑器设置¶
在 ~/.config/zed/settings.json 中添加自定义 ACP 代理(或使用 Zed 的设置 UI):
{
"agent_servers": {
"OpenClaw ACP": {
"type": "custom",
"command": "openclaw",
"args": ["acp"],
"env": {}
}
}
}
要指向特定的 Gateway 或代理:
{
"agent_servers": {
"OpenClaw ACP": {
"type": "custom",
"command": "openclaw",
"args": [
"acp",
"--url",
"wss://gateway-host:18789",
"--token",
"<token>",
"--session",
"agent:design:main"
],
"env": {}
}
}
}
在 Zed 中,打开 Agent 面板并选择 "OpenClaw ACP" 以开始一个线程。
会话映射¶
默认情况下,ACP 桥接会话会获得带有 acp-bridge: 前缀的隔离 Gateway 会话键。这些普通模型桥接会话是合成且可丢弃的:它们会受到过期条目清理的影响,并且不被视为受保护的人类对话界面。要重用已知会话,请传递会话键或标签:
--session <key>:使用特定的 Gateway 会话键。--session-label <label>:按标签解析现有会话。--reset-session:为该键生成新的会话 id(相同键,新对话记录)。
如果你的 ACP 客户端支持元数据,你可以按会话覆盖:
{
"_meta": {
"sessionKey": "agent:main:main",
"sessionLabel": "support inbox",
"resetSession": true
}
}
在 /concepts/session 中了解有关会话键的更多信息。
选项¶
--url <url>:Gateway WebSocket URL(配置时默认为gateway.remote.url)。--token <token>:Gateway 身份验证 token。--token-file <path>:从文件读取 Gateway 身份验证 token。--password <password>:Gateway 身份验证密码。--password-file <path>:从文件读取 Gateway 身份验证密码。--session <key>:默认会话键。--session-label <label>:要解析的默认会话标签。--require-existing:如果会话键/标签不存在则失败。--reset-session:首次使用前重置会话键。--no-prefix-cwd:不要使用工作目录作为 prompt 前缀。--provenance <off|meta|meta+receipt>:包含 ACP 来源元数据或回执。--verbose, -v:向 stderr 输出详细日志。
安全说明:
- 在某些系统上,
--token和--password可能在本地进程列表中可见。优先使用--token-file/--password-file或环境变量(OPENCLAW_GATEWAY_TOKEN、OPENCLAW_GATEWAY_PASSWORD)。 - Gateway 身份验证解析遵循其他 Gateway 客户端使用的共享契约:
- 本地模式:
gateway.auth.*,然后环境变量(OPENCLAW_GATEWAY_*),仅当gateway.auth.*未设置时回退到gateway.remote.*(已配置但未解析的本地 SecretRef 会失败关闭,而不是静默回退) - 远程模式:
gateway.remote.*,按远程优先级规则进行环境变量/配置回退 --url是覆盖安全的,并且不会重用隐式配置/环境变量凭据;请显式传递--token/--password(或文件变体)
acp client 选项¶
--cwd <dir>: ACP 会话的工作目录。--server <command>: ACP 服务器命令(默认:openclaw)。--server-args <args...>: 传递给 ACP 服务器的额外参数。--server-verbose: 在 ACP 服务器上启用详细日志。--verbose, -v: 客户端详细日志。openclaw acp client会在派生的桥接进程上设置OPENCLAW_SHELL=acp-client,可用于特定上下文的 shell/profile 规则。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw