ACP

執行 Agent Client Protocol (ACP) 橋接器，以與 OpenClaw 閘道通訊。

openclaw acp 透過 stdio 為 IDE 提供 ACP 通訊，並透過 WebSocket 將提示轉送至閘道，同時維持 ACP 工作階段與閘道工作階段金鑰的對應。這是由閘道支援的 ACP 橋接器，而非完整的 ACP 原生編輯器執行環境：其重點在於工作階段路由、提示傳遞與串流更新。

若你希望外部 MCP 用戶端直接與 OpenClaw 頻道對話通訊，而非代管 ACP 控制框架工作階段，請改用 openclaw mcp serve。

這不是什麼

openclaw acp 表示 OpenClaw 會作為 ACP 伺服器：IDE 或 ACP 用戶端連線至 OpenClaw，而 OpenClaw 將該工作轉送至閘道工作階段。

這與 ACP 代理程式不同；在後者中，OpenClaw 會透過 acpx 執行 Codex 或 Claude Code 等外部控制框架。

快速判斷原則：

• 編輯器／用戶端想要透過 ACP 與 OpenClaw 通訊：使用 openclaw acp
• OpenClaw 應將 Codex／Claude／Gemini 作為 ACP 控制框架啟動：使用 /acp spawn 和 ACP 代理程式

相容性矩陣

已知限制

• loadSession 僅會為橋接器建立的工作階段重播完整的 ACP 事件分類帳歷程記錄。較舊或沒有分類帳的工作階段會使用逐字稿備援，且不會重建歷史工具呼叫或系統通知。
• 若多個 ACP 用戶端共用相同的閘道工作階段金鑰，事件與取消路由會採取盡力而為的方式，而非依用戶端嚴格隔離。需要乾淨的編輯器本機回合時，請優先使用預設的隔離 acp-bridge:<uuid> 工作階段。
• 閘道停止狀態會轉換為 ACP 停止原因，但該對應方式的表達能力不如完整的 ACP 原生執行環境。
• 工作階段控制項只公開一組精簡的閘道調整項目：思考層級、工具詳細程度、推理、用量詳細資料與提升權限的動作。模型選擇與執行主機控制項不會公開為 ACP 設定選項。
• session_info_update 與 usage_update 衍生自閘道工作階段快照，而非即時 ACP 原生執行環境計量。用量為近似值、不含成本資料，且僅在閘道將權杖總數資料標記為最新時發出。
• 工具跟隨資料採取盡力而為的方式：橋接器會公開已知工具引數／結果中出現的檔案路徑，但不會發出 ACP 終端機或結構化檔案差異。
• 執行核准轉送僅限於進行中的 ACP 提示回合；來自其他閘道工作階段的核准將被忽略。

用法

openclaw acp # 遠端閘道openclaw acp --url wss://gateway-host:18789 --token <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" # 在第一個提示前重設工作階段金鑰openclaw acp --session agent:main:main --reset-session

ACP 用戶端（偵錯）

使用內建 ACP 用戶端，在不使用 IDE 的情況下對橋接器進行基本健全性檢查。它會產生 ACP 橋接器，並讓你以互動方式輸入提示。

openclaw acp client # 將產生的橋接器指向遠端閘道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）。
• ACP 僅會自動核准範圍狹窄的唯讀類別：作用中 cwd 下限定範圍的 read 呼叫，以及唯讀搜尋工具（search、web_search、memory_search）。未知／非核心工具、範圍外讀取、可執行工具、控制平面工具、會修改內容的工具，以及互動式流程，一律需要明確的提示核准。
• 伺服器提供的 toolCall.kind 會視為不受信任的中繼資料，而非授權來源。
• 此 ACP 橋接器原則與 ACPX 控制框架權限分開。若你透過 acpx 後端執行 OpenClaw，plugins.entries.acpx.config.permissionMode=approve-all 是該控制框架工作階段的緊急「yolo」開關。

通訊協定煙霧測試

若要進行通訊協定層級偵錯，請以隔離狀態啟動閘道，並使用 ACP JSON-RPC 用戶端透過 stdio 驅動 openclaw acp。涵蓋 initialize、session/new、帶有絕對 cwd 的 session/list、session/resume、session/close、重複關閉，以及不存在的繼續操作。

證明應包含公告的生命週期功能、由閘道支援的工作階段資料列、更新通知，以及閘道 sessions.list 記錄：

{  "initialize": {    "protocolVersion": 1,    "agentCapabilities": {      "sessionCapabilities": {        "list": {},        "resume": {},        "close": {}      }    }  },  "listSessions": {    "sessions": [      {        "sessionId": "agent:main:acp-smoke",        "cwd": "/path/to/workspace",        "_meta": {          "sessionKey": "agent:main:acp-smoke",          "kind": "direct"        }      }    ],    "nextCursor": null  },  "notifications": ["session_info_update", "available_commands_update", "usage_update"],  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]}

避免只使用 openclaw gateway call sessions.list 作為唯一的 ACP 證明。該命令列介面路徑可能要求提升為新權杖的操作員範圍；ACP 橋接器的正確性應透過 ACP stdio 框架加上閘道 sessions.list 記錄來證明。

如何使用

當 IDE（或其他用戶端）支援 Agent Client Protocol，且你希望它驅動 OpenClaw 閘道工作階段時，請使用 ACP。

1. 確認閘道正在執行（本機或遠端）。
2. 設定閘道目標（透過設定或旗標）。
3. 將 IDE 指向透過 stdio 執行 openclaw acp。

設定範例（持久化）：

openclaw config set gateway.remote.url wss://gateway-host:18789openclaw 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

選擇代理程式

ACP 不會直接選取代理程式，而是依照閘道工作階段金鑰進行路由。請使用代理程式範圍的工作階段金鑰來指定特定代理程式：

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

每個 ACP 工作階段都會對應至單一閘道工作階段金鑰。一個代理程式可以有多個工作階段；除非你覆寫金鑰或標籤，否則 ACP 預設會使用隔離的 acp-bridge:<uuid> 工作階段。

橋接模式不支援每個工作階段的 mcpServers。如果 ACP 用戶端在 newSession 或 loadSession 期間傳送這些內容，橋接器會傳回明確錯誤，而不會直接忽略。

若要讓以 ACPX 為後端的工作階段存取 OpenClaw 外掛工具，或 cron 等選定的內建工具，請啟用閘道端的 ACPX MCP 橋接器，而不要嘗試傳遞每個工作階段的 mcpServers。請參閱 ACP 代理程式和 OpenClaw 工具 MCP 橋接器。

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

若要讓 Codex 或 Claude Code 等程式設計代理程式透過 ACP 與你的 OpenClaw 機器人通訊，請使用內建 openclaw 目標的 acpx。

一般流程：

1. 執行閘道，並確認 ACP 橋接器能連線至該閘道。
2. 將 acpx openclaw 指向 openclaw acp。
3. 指定你希望程式設計代理程式使用的 OpenClaw 工作階段金鑰。

範例：

# 向預設 OpenClaw ACP 工作階段傳送單次請求acpx openclaw exec "摘要說明作用中的 OpenClaw 工作階段狀態。" # 建立持續存在的具名工作階段，以供後續對話使用acpx openclaw sessions ensure --name codex-bridgeacpx openclaw -s codex-bridge --cwd /path/to/repo \  "向我的 OpenClaw 工作代理程式詢問與此儲存庫相關的近期脈絡。"

若要讓 acpx openclaw 每次都指定特定閘道和工作階段金鑰，請在 ~/.acpx/config.json 中覆寫 openclaw 代理程式命令：

{  "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 簽出，請使用直接的命令列介面進入點，而不要使用開發執行器，以保持 ACP 串流乾淨：

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

這是讓 Codex、Claude Code 或其他支援 ACP 的用戶端從 OpenClaw 代理程式取得脈絡資訊，而不必擷取終端畫面的最簡單方式。

Zed 編輯器設定

在 ~/.config/zed/settings.json 中新增自訂 ACP 代理程式（或使用 Zed 的 Settings UI）：

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

若要指定特定閘道或代理程式：

{  "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-bridge: 前置字串的隔離閘道工作階段金鑰。這些一般模型橋接工作階段是合成且可捨棄的：它們會受到過期項目清除機制影響，且不會視為受保護的人類對話介面。若要重複使用已知的工作階段，請傳遞工作階段金鑰或標籤：

• --session <key>：使用特定的閘道工作階段金鑰。
• --session-label <label>：依標籤解析現有工作階段。
• --reset-session：為該金鑰建立新的工作階段 ID（相同金鑰、新的對話記錄）。

如果你的 ACP 用戶端支援中繼資料，可以針對每個工作階段覆寫：

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

若要進一步瞭解工作階段金鑰，請參閱 /concepts/session。

選項

• --url <url>：閘道 WebSocket URL（設定後預設為 gateway.remote.url）。
• --token <token>：閘道驗證權杖。
• --token-file <path>：從檔案讀取閘道驗證權杖。
• --password <password>：閘道驗證密碼。
• --password-file <path>：從檔案讀取閘道驗證密碼。
• --session <key>：預設工作階段金鑰。
• --session-label <label>：要解析的預設工作階段標籤。
• --require-existing：若工作階段金鑰／標籤不存在則失敗。
• --reset-session：在第一次使用前重設工作階段金鑰。
• --no-prefix-cwd：不要在提示詞前加上工作目錄。
• --provenance <off|meta|meta+receipt>：包含 ACP 來源中繼資料或收據。
• --verbose, -v：將詳細記錄輸出至 stderr。

安全性注意事項：

• --token 和 --password 在某些系統的本機程序清單中可能可見。建議優先使用 --token-file/--password-file 或環境變數（OPENCLAW_GATEWAY_TOKEN、OPENCLAW_GATEWAY_PASSWORD）。
• 閘道驗證解析遵循其他閘道用戶端使用的共用契約：
  • 本機模式：先使用環境變數（OPENCLAW_GATEWAY_*），再使用 gateway.auth.*；僅在未設定 gateway.auth.* 時，才回復使用 gateway.remote.*（已設定但無法解析的本機 SecretRef 會採取封閉式失敗，而不會直接回復）
  • 遠端模式：依遠端優先順序規則使用 gateway.remote.*，並以環境變數／設定作為回復選項
  • --url 可安全覆寫，且不會重複使用隱含的設定／環境認證資訊；請明確傳入 --token/--password（或其檔案變體）

acp client 選項

• --cwd <dir>：ACP 工作階段的工作目錄。
• --server <command>：ACP 伺服器命令（預設：openclaw）。
• --server-args <args...>：傳遞給 ACP 伺服器的額外引數。
• --server-verbose：啟用 ACP 伺服器的詳細記錄。
• --verbose, -v：詳細用戶端記錄。
• openclaw acp client 會在產生的橋接程序上設定 OPENCLAW_SHELL=acp-client，可用於依脈絡套用特定的 shell／設定檔規則。

相關內容

• 命令列介面參考
• ACP 代理程式