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 代理程式

​

相容性矩陣

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:<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: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

​

選擇代理程式

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

openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw 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-bridge
acpx 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 代理程式