> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # ACP 執行 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) 橋接器，以與 OpenClaw 閘道通訊。 `openclaw acp` 透過 stdio 為 IDE 提供 ACP 通訊，並透過 WebSocket 將提示轉送至閘道，同時維持 ACP 工作階段與閘道工作階段金鑰的對應。這是由閘道支援的 ACP 橋接器，而非完整的 ACP 原生編輯器執行環境：其重點在於工作階段路由、提示傳遞與串流更新。 若你希望外部 MCP 用戶端直接與 OpenClaw 頻道對話通訊，而非代管 ACP 控制框架工作階段，請改用 [`openclaw mcp serve`](/zh-TW/cli/mcp)。 ## 這不是什麼 `openclaw acp` 表示 OpenClaw 會作為 ACP 伺服器：IDE 或 ACP 用戶端連線至 OpenClaw，而 OpenClaw 將該工作轉送至閘道工作階段。 這與 [ACP 代理程式](/zh-TW/tools/acp-agents)不同；在後者中，OpenClaw 會透過 `acpx` 執行 Codex 或 Claude Code 等外部控制框架。 快速判斷原則： * 編輯器／用戶端想要透過 ACP 與 OpenClaw 通訊：使用 `openclaw acp` * OpenClaw 應將 Codex／Claude／Gemini 作為 ACP 控制框架啟動：使用 `/acp spawn` 和 [ACP 代理程式](/zh-TW/tools/acp-agents) ## 相容性矩陣 | ACP 領域 | 狀態 | 備註 | | --------------------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------- | | `initialize`、`newSession`、`prompt`、`cancel` | 已實作 | 透過 stdio 至閘道 chat/send + abort 的核心橋接流程。 | | `listSessions`、斜線命令 | 已實作 | 工作階段清單會針對閘道工作階段狀態運作，採用有限的游標分頁；當閘道工作階段資料列帶有工作區中繼資料時，會套用 `cwd` 篩選；命令則透過 `available_commands_update` 公告。 | | 工作階段譜系中繼資料 | 已實作 | 工作階段清單與工作階段資訊快照會在 `_meta` 中包含 OpenClaw 父子譜系，讓 ACP 用戶端無須使用私有閘道旁路頻道即可呈現子代理程式關係圖。 | | `resumeSession`、`closeSession` | 已實作 | 繼續會將 ACP 工作階段重新繫結至現有閘道工作階段，而不重播歷程記錄。關閉會取消進行中的橋接工作、將待處理的提示解析為已取消，並釋放橋接工作階段狀態。 | | `loadSession` | 部分支援 | 將 ACP 工作階段重新繫結至閘道工作階段金鑰，並為橋接器建立的工作階段重播 ACP 事件分類帳歷程記錄。較舊或沒有分類帳的工作階段會改用已儲存的使用者／助理文字。 | | 提示內容（`text`、嵌入式 `resource`、影像） | 部分支援 | 文字／資源會扁平化為聊天輸入；影像會成為閘道附件。 | | 工作階段模式 | 部分支援 | 支援 `session/set_mode`；橋接器會公開由閘道支援的工作階段控制項，包括思考層級、工具詳細程度、推理、用量詳細資料與提升權限的動作。更廣泛的 ACP 原生模式／設定介面仍不在範圍內。 | | 思考串流 | 已實作 | 模型思考內容會以 `agent_thought_chunk` 工作階段更新的形式串流傳送。不會發出 ACP 原生工作階段計畫。 | | 工作階段資訊與用量更新 | 部分支援 | 橋接器會根據快取的閘道工作階段快照，發出 `session_info_update` 與盡力而為的 `usage_update` 通知。用量為近似值，且僅在閘道權杖總數標記為最新時傳送。 | | 工具串流 | 部分支援 | 當閘道工具引數／結果公開相關資訊時，`tool_call`／`tool_call_update` 事件會包含原始輸入／輸出、文字內容，以及盡力而為的檔案位置。不會公開嵌入式終端機與更豐富的差異原生輸出。 | | 執行核准 | 部分支援 | 進行中的 ACP 提示回合期間，閘道執行核准提示會透過 `session/request_permission` 轉送至 ACP 用戶端。 | | 每個工作階段的 MCP 伺服器（`mcpServers`） | 不支援 | 橋接模式會拒絕每個工作階段的 MCP 伺服器要求。請改為在 OpenClaw 閘道或代理程式上設定 MCP。 | | 用戶端檔案系統方法（`fs/read_text_file`、`fs/write_text_file`） | 不支援 | 橋接器不會呼叫 ACP 用戶端檔案系統方法。 | | 用戶端終端機方法（`terminal/*`） | 不支援 | 橋接器不會建立 ACP 用戶端終端機，也不會透過工具呼叫串流傳送終端機 ID。 | ## 已知限制 * `loadSession` 僅會為橋接器建立的工作階段重播完整的 ACP 事件分類帳歷程記錄。較舊或沒有分類帳的工作階段會使用逐字稿備援，且不會重建歷史工具呼叫或系統通知。 * 若多個 ACP 用戶端共用相同的閘道工作階段金鑰，事件與取消路由會採取盡力而為的方式，而非依用戶端嚴格隔離。需要乾淨的編輯器本機回合時，請優先使用預設的隔離 `acp-bridge:` 工作階段。 * 閘道停止狀態會轉換為 ACP 停止原因，但該對應方式的表達能力不如完整的 ACP 原生執行環境。 * 工作階段控制項只公開一組精簡的閘道調整項目：思考層級、工具詳細程度、推理、用量詳細資料與提升權限的動作。模型選擇與執行主機控制項不會公開為 ACP 設定選項。 * `session_info_update` 與 `usage_update` 衍生自閘道工作階段快照，而非即時 ACP 原生執行環境計量。用量為近似值、不含成本資料，且僅在閘道將權杖總數資料標記為最新時發出。 * 工具跟隨資料採取盡力而為的方式：橋接器會公開已知工具引數／結果中出現的檔案路徑，但不會發出 ACP 終端機或結構化檔案差異。 * 執行核准轉送僅限於進行中的 ACP 提示回合；來自其他閘道工作階段的核准將被忽略。 ## 用法 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw acp # 遠端閘道 openclaw acp --url wss://gateway-host:18789 --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 橋接器，並讓你以互動方式輸入提示。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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` 記錄： ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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`。 設定範例（持久化）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set gateway.remote.url wss://gateway-host:18789 openclaw config set gateway.remote.token ``` 直接執行範例（不寫入設定）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw acp --url wss://gateway-host:18789 --token # 建議使用，以確保本機程序安全 openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token ``` ## 選擇代理程式 ACP 不會直接選取代理程式，而是依照閘道工作階段金鑰進行路由。請使用代理程式範圍的工作階段金鑰來指定特定代理程式： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw acp --session agent:main:main openclaw acp --session agent:design:main openclaw acp --session agent:qa:bug-123 ``` 每個 ACP 工作階段都會對應至單一閘道工作階段金鑰。一個代理程式可以有多個工作階段；除非你覆寫金鑰或標籤，否則 ACP 預設會使用隔離的 `acp-bridge:` 工作階段。 橋接模式不支援每個工作階段的 `mcpServers`。如果 ACP 用戶端在 `newSession` 或 `loadSession` 期間傳送這些內容，橋接器會傳回明確錯誤，而不會直接忽略。 若要讓以 ACPX 為後端的工作階段存取 OpenClaw 外掛工具，或 `cron` 等選定的內建工具，請啟用閘道端的 ACPX MCP 橋接器，而不要嘗試傳遞每個工作階段的 `mcpServers`。請參閱 [ACP 代理程式](/zh-TW/tools/acp-agents-setup#plugin-tools-mcp-bridge)和 [OpenClaw 工具 MCP 橋接器](/zh-TW/tools/acp-agents-setup#openclaw-tools-mcp-bridge)。 ## 從 `acpx` 使用（Codex、Claude、其他 ACP 用戶端） 若要讓 Codex 或 Claude Code 等程式設計代理程式透過 ACP 與你的 OpenClaw 機器人通訊，請使用內建 `openclaw` 目標的 `acpx`。 一般流程： 1. 執行閘道，並確認 ACP 橋接器能連線至該閘道。 2. 將 `acpx openclaw` 指向 `openclaw acp`。 3. 指定你希望程式設計代理程式使用的 OpenClaw 工作階段金鑰。 範例： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 向預設 OpenClaw ACP 工作階段傳送單次請求 acpx openclaw exec "摘要說明作用中的 OpenClaw 工作階段狀態。" # 建立持續存在的具名工作階段，以供後續對話使用 acpx openclaw sessions ensure --name codex-bridge acpx openclaw -s codex-bridge --cwd /path/to/repo \ "向我的 OpenClaw 工作代理程式詢問與此儲存庫相關的近期脈絡。" ``` 若要讓 `acpx openclaw` 每次都指定特定閘道和工作階段金鑰，請在 `~/.acpx/config.json` 中覆寫 `openclaw` 代理程式命令： ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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 串流乾淨： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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）： ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "agent_servers": { "OpenClaw ACP": { "type": "custom", "command": "openclaw", "args": ["acp"], "env": {} } } } ``` 若要指定特定閘道或代理程式： ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "agent_servers": { "OpenClaw ACP": { "type": "custom", "command": "openclaw", "args": [ "acp", "--url", "wss://gateway-host:18789", "--token", "", "--session", "agent:design:main" ], "env": {} } } } ``` 在 Zed 中，開啟 Agent 面板並選取 "OpenClaw ACP" 以開始討論串。 ## 工作階段對應 依預設，ACP 橋接工作階段會取得具有 `acp-bridge:` 前置字串的隔離閘道工作階段金鑰。這些一般模型橋接工作階段是合成且可捨棄的：它們會受到過期項目清除機制影響，且不會視為受保護的人類對話介面。若要重複使用已知的工作階段，請傳遞工作階段金鑰或標籤： * `--session `：使用特定的閘道工作階段金鑰。 * `--session-label