acp

執行 Agent Client Protocol (ACP) 橋接器，連線至 OpenClaw Gateway。

這個指令透過 stdio 與 IDE 溝通 ACP 協定，再透過 WebSocket 將提示轉發給 Gateway，並維護 ACP 工作階段與 Gateway session key 的對應關係。

openclaw acp 是一個以 Gateway 為後端的 ACP 橋接器，並非完整的 ACP 原生編輯器執行環境。它專注於工作階段路由、提示傳遞，以及基本的串流更新。

相容性矩陣

已知限制

• loadSession 會重播已儲存的使用者與助手文字歷史，但不會重建歷史工具呼叫、系統通知或更豐富的 ACP 原生事件類型。
• 如果多個 ACP 用戶端共用同一個 Gateway session key，事件與取消路由為盡力而為，並非嚴格按用戶端隔離。需要乾淨的編輯器本地對話輪次時，建議使用預設的隔離 acp:<uuid> 工作階段。
• Gateway 停止狀態會轉譯為 ACP stop reason，但對應精度不如完整的 ACP 原生執行環境。
• 目前的初始工作階段控制項只涵蓋部分 Gateway 設定：思考層級、工具詳細程度、推理、用量細節與提權操作。模型選擇和執行主機控制尚未以 ACP 設定選項開放。
• session_info_update 與 usage_update 來自 Gateway 工作階段快照，而非即時的 ACP 原生執行環境計量。用量為近似值，不含費用資料，且僅在 Gateway 標記 token 總量為最新時才會發送。
• 工具追蹤資料為盡力而為。橋接器可以從已知工具參數/結果中提取檔案路徑，但尚未支援 ACP 終端機或結構化檔案 diff。

用法

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

# 連接至現有的 session key
openclaw acp --session agent:main:main

# 以標籤連接（必須已存在）
openclaw acp --session-label "support inbox"

# 在首次提示前重設 session key
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，而你希望它驅動 OpenClaw Gateway 工作階段時，就使用 ACP。

1. 確認 Gateway 正在執行（本地或遠端）。
2. 設定 Gateway 目標（透過設定檔或旗標）。
3. 將 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

選擇 agent

ACP 不會直接選擇 agent，而是透過 Gateway session key 進行路由。

使用 agent 範圍的 session key 來指定特定 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> 工作階段。

橋接模式不支援每工作階段的 mcpServers。如果 ACP 用戶端在 newSession 或 loadSession 時傳送它們，橋接器會回傳明確的錯誤，而非靜默忽略。

從 acpx 使用（Codex、Claude 及其他 ACP 用戶端）

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

常見流程：

1. 啟動 Gateway，確保 ACP 橋接器可以連線。
2. 將 acpx openclaw 指向 openclaw acp。
3. 指定你希望程式碼 agent 使用的 OpenClaw session key。

範例：

# 單次請求至預設的 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 和 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"
    }
  }
}

若是本地 OpenClaw checkout 的 repo，請使用直接的 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」即可開始對話。

工作階段對應

預設情況下，ACP 工作階段會取得帶有 acp: 前綴的隔離 Gateway session key。 若要重複使用已知的工作階段，可傳入 session key 或標籤：

• --session <key>：使用特定的 Gateway session key。
• --session-label <label>：以標籤解析現有的工作階段。
• --reset-session：為該 key 建立全新的 session id（相同 key，新的對話記錄）。

如果你的 ACP 用戶端支援中繼資料，可以逐工作階段覆蓋：

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

進一步了解 session key，請參閱 /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>：預設要解析的工作階段標籤。
• --require-existing：若 session key/標籤不存在則失敗。
• --reset-session：首次使用前重設 session key。
• --no-prefix-cwd：不在提示前加上工作目錄。
• --verbose, -v：將詳細日誌輸出至 stderr。

安全提醒：

• --token 和 --password 在某些系統上可能透過本地處理程序列表被看到。
• 建議改用 --token-file/--password-file 或環境變數（OPENCLAW_GATEWAY_TOKEN、OPENCLAW_GATEWAY_PASSWORD）。
• Gateway 驗證解析遵循其他 Gateway 用戶端共用的協議：
  • 本地模式：env（OPENCLAW_GATEWAY_*）-> gateway.auth.* -> gateway.remote.* 僅在 gateway.auth.* 未設定時作為後備（已設定但無法解析的本地 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：啟用用戶端詳細日誌。