acp

运行与 Clawdbot Gateway 通信的 ACP (Agent Client Protocol) 桥接器。

此命令通过 stdio 为 IDE 提供 ACP 协议支持，并通过 WebSocket 将提示词（prompts）转发到 Gateway。它保持 ACP 会话与 Gateway 会话密钥（session keys）之间的映射。

用法

clawdbot acp

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

# 附加到现有的会话密钥
clawdbot acp --session agent:main:main

# 通过标签附加（必须已存在）
clawdbot acp --session-label "support inbox"

# 在第一个提示词之前重置会话密钥
clawdbot acp --session agent:main:main --reset-session

ACP 客户端 (调试用)

使用内置的 ACP 客户端在没有 IDE 的情况下对桥接器进行冒烟测试。它会启动 ACP 桥接器并让你交互式地输入提示词。

clawdbot acp client

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

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

如何使用

当 IDE（或其他客户端）支持 Agent Client Protocol 且你想让它驱动 Clawdbot Gateway 会话时，请使用 ACP。

确保 Gateway 正在运行（本地或远程）。
配置 Gateway 目标（通过配置或标志位）。
将你的 IDE 指向通过 stdio 运行的 clawdbot acp。

示例配置（持久化）：

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

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

clawdbot acp --url wss://gateway-host:18789 --token <token>

选择 Agent

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

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

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

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

Zed 编辑器设置

在 ~/.config/zed/settings.json 中添加自定义 ACP Agent（或使用 Zed 的设置界面）：

{
  "agent_servers": {
    "Clawdbot ACP": {
      "type": "custom",
      "command": "clawdbot",
      "args": ["acp"],
      "env": {}
    }
  }
}

要针对特定的 Gateway 或 Agent：

{
  "agent_servers": {
    "Clawdbot ACP": {
      "type": "custom",
      "command": "clawdbot",
      "args": [
        "acp",
        "--url", "wss://gateway-host:18789",
        "--token", "<token>",
        "--session", "agent:design:main"
      ],
      "env": {}
    }
  }
}

在 Zed 中，打开 Agent 面板并选择 “Clawdbot ACP” 来启动一个线程。

会话映射

默认情况下，ACP 会话会获得一个带有 acp: 前缀的隔离 Gateway 会话密钥。要重用已知会话，请传递会话密钥或标签：

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

如果你的 ACP 客户端支持元数据（metadata），你可以按会话进行覆盖：

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

在 /concepts/session 了解更多关于会话密钥的信息。

选项

--url <url>：Gateway WebSocket URL（如果已配置，默认为 gateway.remote.url）。
--token <token>：Gateway 身份验证令牌。
--password <password>：Gateway 身份验证密码。
--session <key>：默认会话密钥。
--session-label <label>：默认要解析的会话标签。
--require-existing：如果会话密钥/标签不存在则失败。
--reset-session：在首次使用前重置会话密钥。
--no-prefix-cwd：不要在提示词前加当前工作目录。
--verbose, -v：向 stderr 输出详细日志。

`acp client` 选项

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

acp

用法​

ACP 客户端 (调试用)​

如何使用​

选择 Agent​

Zed 编辑器设置​

会话映射​

选项​

acp client 选项​

用法