ACP 代理程式

• 若已設定 plugins.allow，它就是限制性的外掛清單，且必須包含 acpx，否則已安裝的 ACP 後端會被刻意阻擋（/acp doctor 會回報缺少的允許清單項目）。
• Codex ACP 轉接器隨 acpx 外掛提供，並會在可行時於本機啟動。
• Codex ACP 使用隔離的 CODEX_HOME 執行。OpenClaw 會從主機 Codex 設定複製受信任的專案信任項目，以及安全的模型／供應商路由設定（model、model_provider、model_reasoning_effort、sandbox_mode，以及安全的 model_providers.<name> 欄位）；驗證、通知與掛鉤只會保留在主機設定中。
• 其他目標工具框架的轉接器可能會在首次使用時，透過 npx 隨選擷取。
• 該工具框架的供應商驗證必須已存在於主機上。
• 若主機無法存取 npm 或網路，首次執行時的轉接器擷取會失敗，直到快取已預先暖機，或透過其他方式安裝轉接器為止。

ACP 會啟動真正的外部工具框架程序。OpenClaw 負責路由、 背景工作狀態、傳遞、繫結及政策；工具框架則負責自身的 供應商登入、模型目錄、檔案系統行為與原生工具。

在歸咎於 OpenClaw 前，請確認：

• /acp doctor 回報後端已啟用且運作正常。
• 設定該允許清單時，acp.allowedAgents 允許此目標 ID。
• 工具框架命令可在閘道主機上啟動。
• 該工具框架具有供應商驗證（claude、codex、gemini、opencode、droid 等）。
• 該工具框架中存在所選模型——模型 ID 無法跨工具框架通用。
• 要求的 cwd 存在且可存取，否則省略 cwd，讓後端使用其預設值。
• 權限模式符合工作需求。非互動式工作階段無法點選原生權限提示，因此大量涉及寫入／執行的程式設計作業，通常需要能以無介面方式繼續執行的 ACPX 權限設定檔。

• 產生作業會建立或恢復 ACP 執行階段工作階段、將 ACP 中繼資料記錄至 OpenClaw 工作階段儲存區，並可能在執行由父項擁有時建立背景工作。
• 即使執行階段工作階段是持久性的，由父項擁有的 ACP 工作階段仍會被視為背景工作；完成通知與跨介面傳遞會透過父項工作通知器進行，而不會像一般面向使用者的聊天工作階段一樣運作。
• 工作維護會關閉已終止或孤立且由父項擁有的單次 ACP 工作階段。只要仍有有效的對話繫結，就會保留持久性 ACP 工作階段；沒有有效繫結的過時持久性工作階段則會關閉，避免其在擁有者工作完成或其工作記錄消失後被悄悄恢復。
• 繫結後的後續訊息會直接傳送至 ACP 工作階段，直到該繫結關閉、取消焦點、重設或到期。
• 閘道命令會留在本機處理。/acp ...、/status 和 /unfocus 絕不會作為一般提示文字傳送至已繫結的 ACP 控制框架。
• cancel 會在後端支援取消時中止目前回合；它不會刪除繫結或工作階段中繼資料。
• close 會從 OpenClaw 的角度結束 ACP 工作階段並移除繫結。若控制框架支援恢復，仍可能保留其自身的上游歷程記錄。
• acpx 外掛會在 close 後清理由 OpenClaw 擁有的包裝函式與轉接器處理程序樹，並在閘道啟動期間清除過時且由 OpenClaw 擁有的 ACPX 孤立處理程序。
• 閒置的執行階段工作程序在內建閒置時間結束後可被清理；已儲存的工作階段中繼資料仍可供 /acp sessions 使用。

啟用時，應路由至原生 Codex 外掛的自然語言觸發語句：

• “將此 Discord 頻道繫結至 Codex。”
• “將此聊天連結至 Codex 討論串 <id>。”
• “顯示 Codex 討論串，然後繫結這一個。”

原生 Codex 對話繫結是預設的聊天控制路徑。 OpenClaw 動態工具仍透過 OpenClaw 執行，而 Codex 原生 工具（例如 shell/apply-patch）則在 Codex 內執行。對於 Codex 原生 工具事件，OpenClaw 會在每個回合注入原生掛鉤轉送器，讓外掛掛鉤 可以封鎖 before_tool_call、觀察 after_tool_call，並透過 OpenClaw 核准流程路由 Codex PermissionRequest 事件。Codex Stop 掛鉤 會轉送至 OpenClaw before_agent_finalize，外掛可在該處要求 再進行一次模型處理，之後 Codex 才完成其回答。此轉送器刻意保持 保守：它不會修改 Codex 原生工具引數， 也不會重寫 Codex 討論串記錄。只有在需要 ACP 執行階段／工作階段模型時，才明確使用 ACP。嵌入式 Codex 支援邊界 記錄於 Codex 控制框架 v1 支援合約。

• 舊版 Codex 模型參照 - 由 doctor 修復的舊版 Codex OAuth／訂閱模型路由。
• openai/* - 用於 OpenAI 代理程式回合的原生 Codex app-server 嵌入式執行階段。
• /codex ... - 原生 Codex 對話控制。
• /acp ... 或 runtime: "acp" - 明確的 ACP/acpx 控制。

應路由至 ACP 執行階段的觸發語句：

• “將此作為單次 Claude Code ACP 工作階段執行，並摘要結果。”
• “在討論串中使用 Gemini 命令列介面執行此工作，然後讓後續互動留在同一個討論串。”
• “透過 ACP 在背景討論串中執行 Codex。”

OpenClaw 會選取 runtime: "acp"、解析控制框架 agentId，並在支援時繫結至 目前的對話或討論串，且會將後續互動路由至 該工作階段，直到關閉／到期。只有在明確指定 ACP/acpx，或原生 Codex 外掛無法執行 所要求的作業時，Codex 才會採用此路徑。

對於 sessions_spawn，只有在 ACP 已啟用、要求者未受沙箱限制，且已載入 ACP 執行階段後端時，才會公開 runtime: "acp"。 acp.dispatch.enabled=false 會暫停 ACP 討論串的自動分派， 但不會隱藏或封鎖明確的 sessions_spawn({ runtime: "acp" }) 呼叫。其目標是 ACP 控制框架 ID，例如 codex、claude、droid、 gemini 或 opencode。除非 agents_list 中的一般 OpenClaw 設定代理程式 ID 已明確使用 agents.entries.*.runtime.type="acp" 設定，否則不要傳入該 ID； 應改用預設子代理程式 執行階段。當 OpenClaw 代理程式設定了 runtime.type="acp" 時，OpenClaw 會使用 runtime.acp.agent 作為底層 控制框架 ID。

• --bind here 與 --thread ... 彼此互斥。
• --bind here 僅適用於宣告支援目前對話繫結的頻道；否則 OpenClaw 會傳回明確的不支援訊息。繫結會在閘道重新啟動後持續存在。
• 在 Discord 上，spawnSessions 會管控 --thread auto|here 的子討論串建立，而非 --bind here。
• 如果未指定 --cwd 而產生至不同的 ACP 代理程式，OpenClaw 預設會繼承目標代理程式的工作區。缺少的繼承路徑（ENOENT/ENOTDIR）會回復至後端預設值；其他存取錯誤（例如 EACCES）則會顯示為產生錯誤。
• 閘道管理命令在已繫結的對話中會留在本機處理，即使一般後續文字會路由至已繫結的 ACP 工作階段，/acp ... 命令仍由 OpenClaw 處理；只要該介面啟用了命令處理，/status 和 /unfocus 也會留在本機處理。

當頻道轉接器已啟用討論串繫結時：

• OpenClaw 會將討論串繫結至目標 ACP 工作階段。
• 該討論串中的後續訊息會路由至已繫結的 ACP 工作階段。
• ACP 輸出會傳遞回同一個討論串。
• 取消焦點／關閉／封存／閒置逾時或最長存續期到期時，會移除繫結。
• /acp close、/acp cancel、/acp status、/status 和 /unfocus 是閘道命令，而非傳送給 ACP 控制框架的提示。

討論串繫結 ACP 所需的功能旗標：

• acp.enabled=true
• acp.dispatch.enabled 預設為開啟（將 false 設定為暫停 ACP 討論串的自動分派；明確的 sessions_spawn({ runtime: "acp" }) 呼叫仍可運作）。
• 啟用頻道轉接器的討論串工作階段產生功能（預設：true）：
  • Discord／Telegram：session.threadBindings.spawnSessions=true

討論串繫結支援依轉接器而異。如果目前的頻道轉接器 不支援討論串繫結，OpenClaw 會傳回明確的 不支援／無法使用訊息。

• 任何公開工作階段／討論串繫結功能的頻道轉接器。
• 目前的內建支援：Discord 討論串／頻道、Telegram 主題（群組／超級群組中的論壇主題與私訊主題）。
• 外掛頻道可透過相同的繫結介面新增支援。

互動式工作階段旨在於可見的聊天介面上持續對話：

• /acp spawn ... --bind here 將目前對話繫結至 ACP 工作階段。
• /acp spawn ... --thread ... 將頻道討論串/主題繫結至 ACP 工作階段。
• 持久設定的 bindings[].type="acp" 會將相符的對話路由至同一個 ACP 工作階段。

已繫結對話中的後續訊息會直接路由至 ACP 工作階段，而 ACP 輸出會傳回至同一個 頻道/討論串/主題。

OpenClaw 傳送至控制框架的內容：

• 一般的受限後續訊息會以提示文字傳送，僅在測試框架／後端支援時才會加上附件。
• /acp 管理命令與本機閘道命令會在分派至 ACP 前遭攔截。
• 執行階段產生的完成事件會依目標具體化。OpenClaw 代理程式會取得 OpenClaw 的內部執行階段內容信封；外部 ACP 測試框架則會取得包含子項結果與指示的純文字提示。絕不可將原始 <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> 信封傳送至外部測試框架，或將其持久儲存為 ACP 使用者逐字稿文字。
• ACP 逐字稿項目會使用使用者可見的觸發文字或純文字完成提示。內部事件中繼資料會盡可能在 OpenClaw 中保持結構化，且不會視為使用者撰寫的聊天內容。

由另一個代理程式執行所衍生的單次 ACP 工作階段是背景 子項，類似子代理程式：

• 父項使用 sessions_spawn({ runtime: "acp", mode: "run" }) 請求執行工作。
• 子項會在自己的 ACP 測試框架工作階段中執行。
• 子項回合會在原生子代理程式衍生所使用的同一個背景通道上執行，因此緩慢的 ACP 測試框架不會阻擋不相關的主要工作階段工作。
• 完成報告會透過任務完成公告路徑回傳。OpenClaw 會先將內部完成中繼資料轉換為純文字 ACP 提示，再傳送至外部測試框架，因此測試框架不會看到僅供 OpenClaw 使用的執行階段內容標記。
• 當需要面向使用者的回覆時，父項會以一般助理語氣改寫子項結果。

不要將此路徑視為父項與 子項之間的點對點聊天。子項已有可將完成結果傳回父項的通道。

sessions_send 可在衍生後指定另一個工作階段。對於一般對等 工作階段，OpenClaw 會在注入訊息後使用代理程式對代理程式（A2A） 的後續路徑：

• 等待目標工作階段的回覆。
• 可選擇讓請求者與目標交換有限次數的後續回合。
• 要求目標產生公告訊息。
• 將該公告傳遞至可見的頻道或討論串。

該 A2A 路徑是對等傳送的備援機制，適用於傳送者需要 可見後續訊息的情況。當不相關的工作階段可查看 ACP 目標並 傳送訊息給它時，此路徑仍會啟用，例如使用寬鬆的 tools.sessions.visibility 設定時。

僅當請求者是其自行擁有、由父項管理的單次 ACP 子項之父項時， OpenClaw 才會略過 A2A 後續處理。在此情況下，於任務完成機制之上 執行 A2A 可能會用子項結果喚醒父項、將父項回覆轉傳回子項， 並形成父項／子項回音 迴圈。對於這種自有子項情況，sessions_send 結果會回報 delivery.status="skipped"，因為完成路徑已負責處理 該結果。

使用 resumeSessionId 繼續先前的 ACP 工作階段，而非 從頭開始。代理程式會透過 session/load 重播其對話記錄， 因此能以先前完整內容繼續進行。

{  "task": "從上次中斷處繼續 — 修正其餘測試失敗",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

常見使用案例：

• 將 Codex 工作階段從筆記型電腦移交至手機 — 要求你的代理程式從上次中斷處繼續。
• 繼續你在命令列介面中以互動方式啟動的程式設計工作階段，現在改由你的代理程式以無介面方式進行。
• 繼續因閘道重新啟動或閒置逾時而中斷的工作。

注意事項：

• resumeSessionId 僅在 runtime: "acp" 時適用；預設子代理程式執行階段會忽略此 ACP 專用欄位。
• streamTo 僅在 runtime: "acp" 時適用；預設子代理程式執行階段會忽略此 ACP 專用欄位。
• resumeSessionId 是主機本機的 ACP／測試框架繼續 ID，而非 OpenClaw 頻道工作階段金鑰；OpenClaw 仍會在分派前檢查 ACP 衍生政策與目標代理程式政策，而載入該上游 ID 的授權則由 ACP 後端或測試框架負責。
• resumeSessionId 會還原上游 ACP 對話記錄；thread 與 mode 仍會正常套用至你正在建立的新 OpenClaw 工作階段，因此 mode: "session" 仍需要 thread: true。
• 目標代理程式必須支援 session/load（Codex 與 Claude Code 均支援）。
• 若找不到工作階段 ID，衍生作業會以明確錯誤失敗，不會無聲地備援至新工作階段。

部署閘道後，請執行即時端對端檢查，而不要只信任 單元測試：

1. 驗證目標主機上已部署的閘道版本與提交。
2. 建立連往即時代理程式的臨時 ACPX 橋接工作階段。
3. 要求該代理程式以 runtime: "acp"、agentId: "codex"、mode: "run" 及任務 Reply with exactly LIVE-ACP-SPAWN-OK 呼叫 sessions_spawn。
4. 驗證 accepted=yes、真實的 childSessionKey，並確認沒有驗證器錯誤。
5. 清理臨時橋接工作階段。

將關卡維持在 mode: "run"，並略過 streamTo: "parent" — 綁定討論串的 mode: "session" 與串流轉送路徑是各自獨立且更完整的 整合流程。