古法编程

Appearance

OpenClaw acp 命令运行 ACP 桥接服务，让支持 Agent Client Protocol 的 IDE 或客户端（如 Codex、Claude Code）通过 stdio 连接到你的 OpenClaw Gateway，实现会话路由、Prompt 转发和流式更新。它专注于会话路由而非完整 ACP 原生运行时，支持初始化、会话管理、斜杠命令、工具调用和 exec 审批中继，但限制包括不支持每会话 MCP 服务器、客户端文件系统和终端方法。要快速验证，运行 openclaw acp client 启动交互式调试客户端。

OpenClaw acp 命令：ACP Bridge IDE 集成配置与限制 ​

openclaw acp 运行 Agent Client Protocol (ACP) 桥接器，通过 stdio 与 IDE 通信，并通过 WebSocket 将 Prompt 转发到 Gateway。它维护 ACP 会话到 Gateway 会话键的映射。

openclaw acp 不是什么 ​

openclaw acp 是 Gateway 支撑的 ACP 桥接，不是完整的 ACP 原生编辑器运行时。它与 ACP Agents 不同——后者让 OpenClaw 通过 acpx 启动外部 harness（如 Codex 或 Claude Code）。

快速区分：

  • 编辑器/客户端想用 ACP 与 OpenClaw 通信：使用 openclaw acp
  • OpenClaw 需要启动 Codex/Claude/Gemini 作为 ACP harness：使用 /acp spawn 和 ACP Agents

怎么配置 openclaw acp ​

  1. 确保 Gateway 正在运行（本地或远程）。
  2. 配置 Gateway 目标（持久化配置或命令行标志）。
  3. 在 IDE 中设置自定义 ACP 服务器命令为 openclaw acp。

持久化配置示例：

bash
openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>

直接运行（不写入配置）：

bash
openclaw acp --url wss://gateway-host:18789 --token <token>
# 推荐使用 token 文件以避免本地进程列表泄露
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

选择目标智能体（Agent） ​

ACP 不直接选择 agent，而是通过 Gateway 会话键路由。使用 agent 作用域的会话键：

bash
openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123

每个 ACP 会话映射到一个 Gateway 会话键。默认使用隔离的 acp:&lt;uuid&gt; 会话，除非指定键或标签。

acpx 接入（Codex、Claude Code 等） ​

让 coding agent（如 Codex 或 Claude Code）与 OpenClaw 机器人通过 ACP 通信，使用 acpx openclaw 目标。

典型流程：

bash
acpx openclaw exec "Summarize the active OpenClaw session state."
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/config.json）：

json
{
  "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 源码，使用直接 CLI 入口点保持 ACP 流干净：

bash
env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

Zed 编辑器配置 ​

在 ~/.config/zed/settings.json 中（或使用 Zed 的 Settings UI）：

json
{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}

指向特定 Gateway 或 agent：

json
{
  "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 功能状态说明
initialize、newSession、prompt、cancel已实现核心桥接流程，通过 stdio 转发到 Gateway chat/send + abort。
listSessions、斜杠命令已实现会话列表基于 Gateway 会话状态，带游标分页和 cwd 过滤；命令通过 available_commands_update 广播。
会话谱系元数据已实现会话列表和快照中包含 OpenClaw 父/子谱系的 _meta，让 ACP 客户端渲染子智能体图。
resumeSession、closeSession已实现Resume 将 ACP 会话重新绑定到现有 Gateway 会话（不重放历史）。Close 取消活跃桥接工作，将待处理 prompt 标记为取消，释放桥接会话状态。
loadSession部分实现重新绑定 ACP 会话到 Gateway 会话键，重放 ACP 事件账本历史（仅限桥接创建的会话）。旧会话/无账本的回退到存储的用户/助手文本。
Prompt 内容（text、内嵌 resource、图片）部分实现文本/资源展平为聊天输入；图片作为 Gateway 附件。
会话模式（session/set_mode）部分实现支持设置思考级别、工具详细程度、推理、使用量详情和提升操作。更广泛的 ACP 原生模式/配置暂不在范围内。
会话信息和使用量更新部分实现从缓存的 Gateway 会话快照发送 session_info_update 和尽力而为的 usage_update。使用量是近似值，仅在 Gateway token 总量标记为新鲜时发送。
工具流式传输（tool_call / tool_call_update）部分实现包含原始 I/O、文本内容，以及 Gateway 工具参数/结果暴露时的文件路径。嵌入终端和结构化 diff 尚未暴露。
Exec 审批中继（session/request_permission）部分实现Gateway exec 审批提示在活跃 ACP prompt 回合中被中继到 ACP 客户端。
每会话 MCP 服务器（mcpServers）不支持桥接模式拒绝每会话 MCP 服务器请求。请在 OpenClaw gateway 或 agent 上配置 MCP。
客户端文件系统方法（fs/read_text_file, fs/write_text_file）不支持桥接器不调用 ACP 客户端文件系统方法。
客户端终端方法（terminal/*）不支持桥接器不创建 ACP 客户端终端，也不通过工具调用传递终端 id。
会话计划 / 思考流式传输不支持桥接器目前只输出文本和工具状态，不发出 ACP plan 或思考更新。

已知限制 ​

  • loadSession 只能为桥接创建的会话重放完整 ACP 事件账本。旧会话/无账本的仍使用文本回退，不重建工具调用或系统通知。
  • 多个 ACP 客户端共享同一 Gateway 会话键时，事件和取消路由是尽力而为而非严格按客户端隔离。需要干净编辑器本地回合时，使用默认隔离的 acp:&lt;uuid&gt; 会话。
  • Gateway 停止状态翻译为 ACP 停止原因，但表达力不如完全原生的 ACP 运行时。
  • 初始会话控制目前只暴露 Gateway 旋钮的子集：思考级别、工具详细程度、推理、使用量详情和提升操作。模型选择和 exec-host 控制尚未作为 ACP 配置选项暴露。
  • session_info_update 和 usage_update 来自 Gateway 会话快照，非实时 ACP 本原运行时计量。使用量为近似值，不含成本数据，仅在 Gateway 将 token 总量标记为新鲜时发出。
  • 工具跟随数据是尽力而为的。桥接器可以暴露出现在已知工具参数/结果中的文件路径，但尚未发出 ACP 终端或结构化 diff。
  • Exec 审批中继仅限于活跃 ACP prompt 回合；其他 Gateway 会话的审批被忽略。

使用命令示例 ​

bash
# 默认本地 Gateway
openclaw acp

# 远程 Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# 附加到已有会话键
openclaw acp --session agent:main:main

# 按标签附加（标签必须已存在）
openclaw acp --session-label "support inbox"

# 首个 Prompt 前重置会话键
openclaw acp --session agent:main:main --reset-session

ACP 客户端（调试模式） ​

无 IDE 时验证桥接器是否正常工作。运行 openclaw acp client 启动交互式输入 Prompt。

bash
openclaw acp client

# 指向远程 Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# 覆盖服务器命令（默认 openclaw）
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

调试模式权限模型：

  • 自动批准基于白名单，仅适用于受信任的核心工具 ID。
  • read 自动批准范围限于当前工作目录（--cwd 设置时）。
  • 只自动批准窄范围的只读类：在活动 cwd 下的 read 调用，以及只读搜索工具（search、web_search、memory_search）。未知/非核心工具、超范围读取、exec 能力工具、控制平面工具、修改工具和交互流程始终需要明确的 prompt 批准。
  • 服务器提供的 toolCall.kind 被视为不可信元数据（不是授权来源）。
  • 此 ACP 桥接策略与 ACPX harness 权限不同。如果通过 acpx 后端运行 OpenClaw，plugins.entries.acpx.config.permissionMode=approve-all 是 harness 会话的 “yolo” 开关。

协议冒烟测试 ​

隔离 Gateway 状态后，通过 stdio 用 ACP JSON-RPC 客户端驱动 openclaw acp，覆盖 initialize、session/new、session/list（带绝对 cwd）、session/resume、session/close、重复关闭和缺失 resume。期望结果应包含生命周能力、Gateway 会话行、更新通知和 Gateway sessions.list 日志。

示例验证框架：

json
{
  "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 日志证明。

会话映射 ​

默认 ACP 会话获得 acp: 前缀的隔离 Gateway 会话键。要复用已知会话：

  • --session &lt;key&gt;：使用特定 Gateway 会话键。
  • --session-label <label>：通过标签解析已有会话。
  • --reset-session：为同一键创建全新会话 id（新 transcript）。

如果 ACP 客户端支持元数据，可覆盖：

json
{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}

了解更多会话键：/openclaw/concepts/session。

选项 ​

  • --url &lt;url&gt;：Gateway WebSocket URL（默认使用 gateway.remote.url 配置）。
  • --token &lt;token&gt;：Gateway 认证 token。
  • --token-file &lt;path&gt;：从文件读取 token。
  • --password &lt;password&gt;：Gateway 认证密码。
  • --password-file &lt;path&gt;：从文件读取密码。
  • --session &lt;key&gt;：默认会话键。
  • --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 认证解析遵循共享约定：
    • 本地模式：env（OPENCLAW_GATEWAY_*）-> gateway.auth.* -> 仅在 gateway.auth.* 未设置时回退到 gateway.remote.*（已配置但未解析的本地 SecretRef 会失败关闭）。
    • 远程模式：gateway.remote.* 按远程优先规则 env/config 回退。
    • --url 是覆盖安全的，不重用隐式 config/env 凭据；需显式传入 --token/--password（或文件变体）。
  • ACP 运行时后端子进程收到 OPENCLAW_SHELL=acp，可用于上下文特定的 shell/profile 规则。
  • openclaw acp client 在启动的桥接进程上设置 OPENCLAW_SHELL=acp-client。

acp client 选项 ​

  • --cwd &lt;dir&gt;：ACP 会话工作目录。
  • --server &lt;command&gt;：ACP 服务器命令（默认 openclaw）。
  • --server-args <args...>：传递给 ACP 服务器的额外参数。
  • --server-verbose：开启 ACP 服务器详细日志。
  • --verbose, -v：开启客户端详细日志。

相关链接 ​

常见问题 ​

openclaw acp 与 ACP Agents 有什么区别？ ​

openclaw acp 是 ACP 桥接器，让 IDE 作为客户端连接 OpenClaw Gateway 并驱动会话。ACP Agents 是让 OpenClaw 启动外部 coding agent（如 Codex、Claude Code）作为 ACP harness 运行。如果编辑器需要与 OpenClaw 交互，用 openclaw acp；如果 OpenClaw 需要启动 coding agent，用 /acp spawn 和 ACP Agents。

在 Zed 里怎么配置 OpenClaw ACP 连接远程 Gateway？ ​

在 ~/.config/zed/settings.json 中添加 agent_servers 条目，设置 command 为 openclaw，args 包含 acp、--url、--token（或 --token-file），以及可选的 --session。然后在 Zed 的 Agent 面板中选择该配置即可开始线程。示例配置见上方 Zed 编辑器配置小节。

loadSession 为什么只部分实现？会影响哪些场景？ ​

loadSession 只能为桥接创建的会话重放 ACP 事件账本历史。对于早期创建或没有事件账本的旧 Gateway 会话，桥接器会回退到用户/助手文本，无法重建历史工具调用、系统通知和原生 ACP 事件。如果你需要完整上下文恢复，建议使用桥接创建的新会话（默认 acp:&lt;uuid&gt; 隔离会话）。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策