acp

运行 Agent Client Protocol (ACP) 桥接器，�?OpenClaw Gateway 通信�?

此命令通过 stdio �?IDE 进行 ACP 通信，并将提示词通过 WebSocket 转发�?Gateway。它保持 ACP 会话�?Gateway 会话密钥的映射�?

用法

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 时，使用 ACP 让它驱动 OpenClaw Gateway 会话�?

确保 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>
# 更适合本地进程安全
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:<uuid> 会话�?

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: 前缀的隔�?Gateway 会话密钥。要重用已知会话，请传递会话密钥或标签�?

--session <key>：使用特定的 Gateway 会话密钥�?
--session-label <label>：通过标签解析现有会话�?
--reset-session：为该密钥生成新的会�?ID（相同密钥，新的记录）�?

如果你的 ACP 客户端支持元数据，可以覆盖每个会话：

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

了解更多关于会话密钥的信息，请参�?/zh/docs/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：不将工作目录前缀添加到提示词�?
--verbose, -v：详细日志输出到 stderr�?

安全注意�?

--token �?--password 在某些系统上可能在本地进程列表中可见�?
优先使用 --token-file/--password-file 或环境变量（OPENCLAW_GATEWAY_TOKEN、OPENCLAW_GATEWAY_PASSWORD）�?

`acp client` 选项

--cwd <dir>：ACP 会话的工作目录�?
--server <command>：ACP 服务器命令（默认：openclaw）�?
--server-args <args...>：传递给 ACP 服务器的额外参数�?
--server-verbose：在 ACP 服务器上启用详细日志�?
--verbose, -v：详细的客户端日志�?

acp

用法