acp

运行 ACP（Agent Client Protocol）桥接，与 OpenClaw Gateway 通信。

这个命令通过 stdio 与 IDE 进行 ACP 通信，并通过 WebSocket 将 Prompt 转发到 Gateway。它会保持 ACP Session 与 Gateway Session 键的映射关系。

用法

openclaw acp

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

# 连接到现有的 Session 键
openclaw acp --session agent:main:main

# 通过标签连接（必须已存在）
openclaw acp --session-label "support inbox"

# 在第一个 Prompt 之前重置 Session 键
openclaw acp --session agent:main:main --reset-session

ACP 客户端（调试）

使用内置的 ACP 客户端来测试桥接，无需 IDE。它会启动 ACP 桥接，让你可以交互式地输入 Prompt。

openclaw acp client

# 将启动的桥接指向远程 Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token <token>

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

如何使用

当 IDE（或其他客户端）使用 Agent Client Protocol，并且你想让它驱动 OpenClaw Gateway Session 时，就用 ACP。

确保 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>

选择 Agent

ACP 不直接选择 Agent。它通过 Gateway Session 键进行路由。

使用 Agent 作用域的 Session 键来指定特定的 Agent：

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

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

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” 来启动对话。

Session 映射

默认情况下，ACP Session 会获得一个带 acp: 前缀的隔离 Gateway Session 键。要复用已知的 Session，传递 Session 键或标签：

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

如果你的 ACP 客户端支持元数据，可以按 Session 覆盖：

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

在 /concepts/session 了解更多关于 Session 键的信息。

选项

--url <url>：Gateway WebSocket URL（配置后默认为 gateway.remote.url）。
--token <token>：Gateway 认证 Token。
--password <password>：Gateway 认证密码。
--session <key>：默认 Session 键。
--session-label <label>：要解析的默认 Session 标签。
--require-existing：如果 Session 键/标签不存在则失败。
--reset-session：在首次使用前重置 Session 键。
--no-prefix-cwd：不在 Prompt 前添加工作目录。
--verbose, -v：详细日志输出到 stderr。

`acp client` 选项

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

acp

用法