ACP

运行 Agent Client Protocol (ACP) 桥接器，用于与 OpenClaw Gateway 通信。

openclaw acp 通过 stdio 与 IDE 进行 ACP 通信，并通过 WebSocket 将 Prompt 转发到 Gateway，同时保持 ACP 会话映射到 Gateway 会话键。它是一个由 Gateway 支持的 ACP 桥接器，而不是完整的原生 ACP 编辑器运行时：它专注于会话路由、Prompt 传递和流式更新。

如果你希望外部 MCP 客户端直接与 OpenClaw 频道对话通信，而不是托管 ACP harness 会话，请改用 openclaw mcp serve。

这不是什么¶

openclaw acp 表示 OpenClaw 充当 ACP 服务器：IDE 或 ACP 客户端连接到 OpenClaw，然后 OpenClaw 将这些工作转发到 Gateway 会话。

这与 ACP Agents 不同，在后者中 OpenClaw 通过 acpx 运行外部 harness，例如 Codex 或 Claude Code。

快速规则：

• 编辑器/客户端希望与 OpenClaw 进行 ACP 通信：使用 openclaw acp
• OpenClaw 应启动 Codex/Claude/Gemini 作为 ACP harness：使用 /acp spawn 和 ACP Agents

兼容性矩阵¶

已知限制¶

• 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 提示轮次；来自其他 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 桥接，并允许你交互式地输入提示。

会话建立后，意外的服务器信号退出会使客户端以状态 1 退出。当显式 exit 或 quit 通过信号停止服务器时，它仍然保持成功。数值服务器退出码会被传播，包括在显式退出期间返回的非零代码。关闭交互式输入（包括在空提示符处按 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）。未知/非核心工具、超出范围的读取、可执行工具、控制平面工具、变更工具和交互式流程始终需要显式提示审批。
• 服务器提供的 toolCall.kind 被视为不可信元数据，而不是授权来源。
• 此 ACP 桥接策略独立于 ACPX 测试框架权限。如果你通过 acpx 后端运行 OpenClaw，则 plugins.entries.acpx.config.permissionMode=approve-all 是该测试框架会话的 break-glass “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 机器人通信，请使用 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 检出，请使用直接 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 的设置界面）：

{
  "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-file <path>：从文件读取 Gateway 身份验证令牌。
• --password <password>：Gateway 身份验证密码。
• --password-file <path>：从文件读取 Gateway 身份验证密码。
• --session <key>：默认会话键。
• --session-label <label>：要解析的默认会话标签。
• --require-existing：如果会话键/标签不存在则失败。
• --reset-session：在首次使用前重置会话键。
• --no-prefix-cwd：不要使用工作目录作为提示前缀。
• --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 规则。

相关¶

• CLI 参考
• ACP 代理