使用 OpenClaw ACP Bridge：快速連接 IDE 與 Gateway

執行 Agent Client Protocol (ACP) bridge 來與 OpenClaw Gateway 通訊。

這個指令透過 stdio 為 IDE 提供 ACP 支援，並透過 WebSocket 將 prompt 轉發到 Gateway。它會負責將 ACP session 對應到 Gateway 的 session key。

openclaw acp 是一個由 Gateway 驅動的 ACP bridge，而不是完整的 ACP 原生編輯器 runtime。它的重點在於 session 路由、prompt 傳遞以及基礎的串流更新。

如果你想讓外部 MCP client 直接與 OpenClaw channel 對話，而不是託管一個 ACP session，請改用 openclaw mcp serve。

相容性矩陣

ACP 領域	狀態	備註
`initialize`, `newSession`, `prompt`, `cancel`	已實作	透過 stdio 到 Gateway chat/send + abort 的核心 bridge 流程。
`listSessions`, 斜線指令	已實作	Session 列表對應 Gateway 的 session 狀態；指令透過 `available_commands_update` 發布。
`loadSession`	部分支援	將 ACP session 重新綁定到 Gateway session key，並重播儲存的使用者/助手文字歷史。目前尚未重建 Tool/system 歷史。
Prompt 內容 (`text`, 嵌入式 `resource`, 圖片)	部分支援	文字/資源會被扁平化為聊天輸入；圖片則轉換為 Gateway 附件。
Session 模式	部分支援	支援 `session/set_mode`，且 bridge 會公開初始的 Gateway session 控制項，包含思考層級、Tool 詳細度、推理、使用詳情和進階操作。更廣泛的 ACP 原生模式/設定目前不在範圍內。
Session 資訊與用量更新	部分支援	Bridge 會根據快取的 Gateway session 快照發送 `session_info_update` 和盡力而為的 `usage_update` 通知。用量是估計值，且僅在 Gateway 標記 token 總數更新時發送。
Tool 串流	部分支援	`tool_call` / `tool_call_update` 事件包含原始 I/O、文字內容，以及當 Gateway tool 參數/結果有提供時的盡力而為檔案位置。目前尚未公開嵌入式終端機和更豐富的 diff 原生輸出。
每個 Session 的 MCP server (`mcpServers`)	不支援	Bridge 模式會拒絕每個 session 的 MCP server 請求。請改在 OpenClaw Gateway 或 agent 上設定 MCP。
Client 檔案系統方法 (`fs/read_text_file`, `fs/write_text_file`)	不支援	Bridge 不會呼叫 ACP client 的檔案系統方法。
Client 終端機方法 (`terminal/*`)	不支援	Bridge 不會建立 ACP client 終端機，也不會透過 tool call 串流終端機 ID。
Session 計畫 / 思考串流	不支援	Bridge 目前只輸出文字和 tool 狀態，不支援 ACP 計畫或思考更新。

已知限制

loadSession 會重播儲存的使用者和助手文字歷史，但不會重建歷史 tool call、系統通知或更豐富的 ACP 原生事件類型。
如果多個 ACP client 共用同一個 Gateway session key，事件和取消路由是盡力而為的，而非嚴格針對每個 client 隔離。當你需要乾淨的編輯器本地回合時，建議使用預設隔離的 acp:<uuid> session。
Gateway 的停止狀態會轉換為 ACP 的停止原因，但這種對應關係不如完全原生的 ACP runtime 那麼豐富。
初始的 session 控制目前只提供 Gateway 的一部分選項：思考層級、Tool 詳細度、推理、使用詳情和進階操作。模型選擇和執行主機控制尚未作為 ACP 設定選項公開。
session_info_update 和 usage_update 是源自 Gateway session 快照，而不是即時的 ACP 原生 runtime 統計。用量是估計值，不包含成本數據，且僅在 Gateway 標記總 token 數據更新時才會發出。
Tool 的追蹤數據是盡力而為的。Bridge 可以顯示出現在已知 tool 參數/結果中的檔案路徑，但目前還不會發出 ACP 終端機或結構化的檔案 diff。

使用方法

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 client (除錯)

使用內建的 ACP client，不需要 IDE 就能對 bridge 進行基本檢查。它會啟動 ACP bridge 並讓你以互動方式輸入 prompt。

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

權限模型（client 除錯模式）：

自動批准是基於白名單的，而且只適用於受信任的核心 tool ID。
read 的自動批准範圍僅限於目前的工作目錄（如果你有設定 --cwd）。
ACP 只會自動批准狹義的唯讀類別：包括在當前 cwd 下的 read 呼叫，以及唯讀搜尋工具（search, web_search, memory_search）。未知的或非核心工具、超出範圍的讀取、具備執行能力的工具、控制層面工具、修改類工具以及互動式流程，一律需要明確的 prompt 批准。
Server 提供的 toolCall.kind 被視為不可信的 metadata，並非授權依據。
這個 ACP bridge 策略與 ACPX harness 權限是分開的。如果你透過 acpx 後端執行 OpenClaw，plugins.entries.acpx.config.permissionMode=approve-all 是該 harness session 的緊急「全開」開關。

如何使用

當你的 IDE（或其他客戶端）支援 Agent Client Protocol，且你想讓它驅動 OpenClaw Gateway 會話時，就可以使用 ACP。

確保 Gateway 正在執行（本地或遠端皆可）。
設定 Gateway 目標（透過設定檔或 flags）。
將你的 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

選擇 Agent

ACP 不會直接挑選 Agent，它是透過 Gateway session key 來進行路由。

使用 Agent 作用域的 session keys 來指定特定的 Agent：

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

每個 ACP 會話都會對應到單一的 Gateway session key。一個 Agent 可以有多個會話；除非你覆蓋了 key 或標籤，否則 ACP 預設會使用一個獨立的 acp:<uuid> 會話。

在 bridge mode 下不支援個別會話的 mcpServers。如果 ACP 客戶端在 newSession 或 loadSession 期間發送這些資訊，bridge 會回傳明確的錯誤，而不是默默忽略它們。

如果你希望基於 ACPX 的會話能看到 OpenClaw plugin tools，請啟用 Gateway 端的 ACPX plugin bridge，而不是嘗試傳遞個別會話的 mcpServers。參考 ACP Agents。

透過 `acpx` 使用 (Codex, Claude, 其他 ACP 客戶端)

如果你想讓 Codex 或 Claude Code 這類 coding agent 透過 ACP 與你的 OpenClaw 機器人溝通，可以使用 acpx 內建的 openclaw 目標。

典型的流程如下：

啟動 Gateway 並確保 ACP bridge 可以連上它。
將 acpx openclaw 指向 openclaw acp。
指定你希望 coding agent 使用的 OpenClaw session key。

範例：

# 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 和 session key，可以在 ~/.acpx/config.json 中覆寫 openclaw agent 指令：

{
  "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"
    }
  }
}

對於 repo 本地的 OpenClaw 檢出版本，請使用直接的 CLI 入口點而不是 dev runner，這樣可以保持 ACP 串流乾淨。例如：

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 的設定介面）：

{
  "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」即可開始對話。

AI Setup Assistant

下一步

Session 對應

預設情況下，ACP session 會獲得一個帶有 acp: 前綴的獨立 Gateway session key。如果要重複使用現有的 session，可以傳入 session key 或 label：

--session <key>: 使用特定的 Gateway session key。
--session-label <label>: 透過 label 解析現有的 session。
--reset-session: 為該 key 產生一個全新的 session id（相同的 key，但新的對話紀錄）。

如果你的 ACP client 支援 metadata，你可以針對每個 session 進行覆蓋：

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

深入了解 session keys：/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 key。
--session-label <label>: 要解析的預設 session label。
--require-existing: 如果 session key/label 不存在則失敗。
--reset-session: 在第一次使用前重設 session key。
--no-prefix-cwd: 不要將工作目錄作為 prompt 的前綴。
--verbose, -v: 輸出詳細日誌到 stderr。

安全注意事項：

--token 和 --password 在某些系統的本地程序列表中可能是可見的。
建議優先使用 --token-file/--password-file 或環境變數（OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD）。
Gateway 認證解析遵循其他 Gateway client 使用的共享規範：
- local 模式：env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> gateway.remote.*（僅在 gateway.auth.* 未設置時回退；已配置但未解析的本地 SecretRefs 會導致失敗）。
- remote 模式：gateway.remote.* 並根據遠端優先級規則進行 env/config 回退。
- --url 是覆蓋安全的，且不會重複使用隱含的 config/env 憑證；請傳入明確的 --token/--password（或檔案變體）。
ACP runtime 後端子程序會收到 OPENCLAW_SHELL=acp，這可以用於特定情境的 shell/profile 規則。
openclaw acp client 會在啟動的 bridge 程序上設置 OPENCLAW_SHELL=acp-client。

`acp client` 選項

--cwd <dir>: ACP session 的工作目錄。
--server <command>: ACP server 命令（預設：openclaw）。
--server-args <args...>: 傳遞給 ACP server 的額外參數。
--server-verbose: 在 ACP server 上啟用詳細日誌。
--verbose, -v: 詳細的 client 日誌。

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。