学了个寂寞

Appearance

acp ​

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

该命令通过 stdio 以 ACP 协议与 IDE 交互，并将 Prompt 通过 WebSocket 转发到 Gateway。它维护 ACP 会话到 Gateway 会话键的映射关系。

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

兼容性矩阵 ​

ACP 功能区域状态说明
initialize、newSession、prompt、cancel已实现核心桥接流程，通过 stdio 转发到 Gateway chat/send + abort。
listSessions、斜杠命令已实现会话列表基于 Gateway 会话状态；命令通过 available_commands_update 广播。
loadSession部分实现将 ACP 会话重新绑定到 Gateway 会话键，并重放已存储的用户/助手文本历史。工具/系统历史尚未重建。
Prompt 内容（text、内嵌 resource、图片）部分实现文本/资源被展平为聊天输入；图片作为 Gateway 附件处理。
会话模式部分实现支持 session/set_mode，桥接器暴露初始 Gateway 支撑的会话控制，包括思考级别、工具详细程度、推理、使用量详情和提升操作。更广泛的 ACP 原生模式/配置界面暂不在范围内。
会话信息和使用量更新部分实现桥接器从缓存的 Gateway 会话快照发出 session_info_update 和尽力而为的 usage_update 通知。使用量为近似值，仅在 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 plan 或思考更新。

已知限制 ​

  • loadSession 重放已存储的用户和助手文本历史，但不重建历史工具调用、系统通知或更丰富的 ACP 原生事件类型。
  • 如果多个 ACP 客户端共享同一 Gateway 会话键，事件和取消路由是尽力而为而非严格按客户端隔离。如果需要干净的编辑器本地回合，请使用默认的隔离 acp:<uuid> 会话。
  • Gateway 停止状态会被转换为 ACP 停止原因，但该映射不如完全原生的 ACP 运行时表达丰富。
  • 初始会话控制目前只暴露 Gateway 旋钮的聚焦子集：思考级别、工具详细程度、推理、使用量详情和提升操作。模型选择和 exec-host 控制尚未作为 ACP 配置选项暴露。
  • session_info_update 和 usage_update 来自 Gateway 会话快照，而非实时 ACP 原生运行时计量。使用量为近似值，不含成本数据，仅在 Gateway 将 token 总量数据标记为新鲜时发出。
  • 工具跟随数据是尽力而为的。桥接器可以暴露出现在已知工具参数/结果中的文件路径，但尚未发出 ACP 终端或结构化文件 diff。

用法 ​

bash
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"

# 第一个 Prompt 前重置会话键
openclaw acp --session agent:main:main --reset-session

ACP 客户端（调试） ​

使用内置 ACP 客户端在无 IDE 的情况下对桥接器做健全性检查。 它会启动 ACP 桥接器，让你以交互方式输入 Prompt。

bash
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 时使用其值）。
  • 未知/非核心工具名称、超出范围的读取和危险工具始终需要明确的 Prompt 审批。
  • 服务器提供的 toolCall.kind 被视为不受信任的元数据（不是授权来源）。

使用方法 ​

当 IDE（或其他客户端）使用 Agent Client Protocol 并希望驱动 OpenClaw Gateway 会话时，使用 ACP。

  1. 确保 Gateway 正在运行（本地或远程）。
  2. 配置 Gateway 目标（通过配置或标志）。
  3. 将 IDE 配置为通过 stdio 运行 openclaw acp。

配置示例（持久化）：

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

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

bash
openclaw acp --url wss://gateway-host:18789 --token <token>
# 本地进程安全性优先，推荐使用 token 文件
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

选择 Agent ​

ACP 不直接选择 agent。它通过 Gateway 会话键来路由。

使用 agent 作用域的会话键来定位特定 agent：

bash
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 等 coding agent 通过 ACP 与你的 OpenClaw 机器人通信，请使用 acpx 的内置 openclaw target。

典型流程：

  1. 运行 Gateway 并确保 ACP 桥接器可以访问它。
  2. 将 acpx openclaw 指向 openclaw acp。
  3. 指定你希望 coding agent 使用的 OpenClaw 会话键。

示例：

bash
# 向默认 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 命令：

json
{
  "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 checkout，请使用直接的 CLI 入口点而非 dev runner，以保持 ACP 流的干净：

bash
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 的 Settings UI）：

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

指向特定 Gateway 或 agent：

json
{
  "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 客户端支持元数据，可以按会话覆盖：

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

了解更多会话键信息：/openclaw/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：不在 Prompt 前添加工作目录前缀。
  • --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：启用详细客户端日志。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策