跳转至

运行与 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。

  1. 确保 Gateway 正在运行(本地或远程)。
  2. 配置 Gateway 目标(配置或标志)。
  3. 让 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 二进制文件。

典型流程:

  1. 在编码代理的机器上安装 acpx CLI 并运行 Gateway,确保 ACP 桥接能够访问它。
  2. 将 acpx openclaw 指向 openclaw acp。
  3. 指定你希望编码代理使用的 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