acp

运行 Agent Client Protocol (ACP) 桥接器，连接到 OpenClaw Gateway。

这个命令通过 stdio 与 IDE 通信（ACP 协议），同时通过 WebSocket 把提示转发给 Gateway。它会在 ACP 会话和 Gateway 会话密钥之间维护映射关系。

openclaw acp 是一个基于 Gateway 的 ACP 桥接器，而不是完整的 ACP 原生编辑器运行时。它专注于会话路由、提示投递和基本的流式更新。

兼容性矩阵

ACP 领域状态说明
initialize, newSession, prompt, cancel已实现核心桥接流程：通过 stdio 对接 Gateway 的 chat/send + abort。
listSessions, 斜杠命令已实现会话列表基于 Gateway 的会话状态；可用命令通过 available_commands_update 广播。
loadSession部分支持将 ACP 会话重新绑定到 Gateway 会话密钥，并回放已存储的用户/助手文本历史。工具和系统历史尚未重建。
提示内容（text、嵌入 resource、图片）部分支持文本和资源会被展平为聊天输入；图片作为 Gateway 附件处理。
会话模式部分支持支持 session/set_mode，桥接器会暴露 Gateway 支持的初始会话控制项——包括思考级别、工具详细度、推理、用量详情和提权操作。更广泛的 ACP 原生模式/配置能力暂不在范围内。
会话信息和用量更新部分支持桥接器会发出 session_info_update 和尽力而为的 usage_update 通知（来自缓存的 Gateway 会话快照）。用量数据是近似值，仅在 Gateway 标记 token 总量为最新时才发送。
工具流式输出部分支持tool_call / tool_call_update 事件包含原始 I/O、文本内容，以及当 Gateway 工具参数/结果中暴露文件位置时的尽力推断。嵌入式终端和更丰富的 diff 原生输出尚未支持。
每会话 MCP 服务器（mcpServers）不支持桥接模式下不支持每会话 MCP 服务器请求。请在 OpenClaw Gateway 或 Agent 端配置 MCP。
客户端文件系统方法（fs/read_text_file, fs/write_text_file）不支持桥接器不会调用 ACP 客户端的文件系统方法。
客户端终端方法（terminal/*）不支持桥接器不会创建 ACP 客户端终端，也不会在工具调用中传输终端 ID。
会话计划 / 思考流不支持桥接器目前只输出文本和工具状态，不发送 ACP 计划或思考更新。

已知限制

  • loadSession 会回放存储的用户和助手文本历史，但不会重建历史工具调用、系统通知或更丰富的 ACP 原生事件类型。
  • 如果多个 ACP 客户端共享同一个 Gateway 会话密钥，事件和取消的路由是尽力而为的，不会严格按客户端隔离。如果需要干净的编辑器本地对话轮次，建议使用默认的 acp:<uuid> 隔离会话。
  • Gateway 的停止状态会被转换为 ACP 停止原因，但这个映射不如完整的 ACP 原生运行时那么精细。
  • 当前的初始会话控制只暴露了 Gateway 配置的一个子集：思考级别、工具详细度、推理、用量详情和提权操作。模型选择和执行主机控制尚未作为 ACP 配置选项暴露。
  • session_info_update 和 usage_update 来自 Gateway 会话快照，而非实时的 ACP 原生运行时计量。用量是近似值，不包含费用数据，仅在 Gateway 标记 token 总量数据为最新时才发送。
  • 工具跟踪数据是尽力而为的。桥接器能提取已知工具参数/结果中出现的文件路径，但尚不支持发送 ACP 终端或结构化文件 diff。

用法

openclaw acp

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

# 远程 Gateway（从文件读取 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"

# 在第一次提示前重置会话密钥
openclaw acp --session agent:main:main --reset-session

ACP 客户端（调试用）

内置的 ACP 客户端可以在不依赖 IDE 的情况下快速验证桥接器是否正常。它会启动 ACP 桥接器并让你交互式地输入提示。

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 时以该目录为准）。
  • 未知/非核心工具名称、超出范围的读取和危险工具始终需要显式确认。
  • 服务端提供的 toolCall.kind 被视为不可信的元数据（不作为授权依据）。

使用方式

当 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>
# 推荐用于本地进程安全
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

选择 Agent

ACP 不直接选择 Agent，而是通过 Gateway 会话密钥进行路由。

使用 Agent 作用域的会话密钥来指定特定 Agent：

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

每个 ACP 会话映射到一个 Gateway 会话密钥。一个 Agent 可以有多个会话；除非你手动覆盖密钥或标签，ACP 默认使用隔离的 acp:<uuid> 会话。

桥接模式不支持每会话 mcpServers。如果 ACP 客户端在 newSession 或 loadSession 时发送了这些配置，桥接器会返回明确的错误，而不是静默忽略。

通过 acpx 使用（Codex、Claude 等 ACP 客户端）

如果你想让 Codex 或 Claude Code 等编程 Agent 通过 ACP 与你的 OpenClaw 机器人对话，可以使用 acpx 内置的 openclaw 目标。

典型流程：

  1. 运行 Gateway，确保 ACP 桥接器能访问到它。
  2. 把 acpx openclaw 指向 openclaw acp。
  3. 指定你希望编程 Agent 使用的 OpenClaw 会话密钥。

示例：

# 一次性请求，使用默认 OpenClaw ACP 会话
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 openclaw 每次都指向特定的 Gateway 和会话密钥，可以在 ~/.acpx/config.json 中覆盖 openclaw Agent 命令：

{
  "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 流的干净。例如：

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

这是让 Codex、Claude Code 或其他 ACP 感知客户端从 OpenClaw Agent 获取上下文信息的最简单方式，不用再去抓取终端输出了。

Zed 编辑器配置

在 ~/.config/zed/settings.json 中添加自定义 ACP Agent（也可以通过 Zed 的设置界面操作）：

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

指定特定 Gateway 或 Agent：

{
  "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: 前缀的隔离 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：不在提示前添加工作目录前缀。
  • --verbose, -v：向 stderr 输出详细日志。

安全提示：

  • --token 和 --password 在某些系统上可能在进程列表中可见。
  • 推荐使用 --token-file/--password-file 或环境变量（OPENCLAW_GATEWAY_TOKEN、OPENCLAW_GATEWAY_PASSWORD）。
  • Gateway 认证解析遵循与其他 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 <dir>：ACP 会话的工作目录。
  • --server <command>：ACP 服务器命令（默认：openclaw）。
  • --server-args <args...>：传递给 ACP 服务器的额外参数。
  • --server-verbose：启用 ACP 服务器的详细日志。
  • --verbose, -v：客户端详细日志。
arrow_back
上一页
Cli
下一页
Agent
arrow_forward