ACP 代理程式

• 如果設定了 plugins.allow，它就是限制性的 Plugin 清單，且必須包含 acpx；否則已安裝的 ACP 後端會被刻意封鎖，而 /acp doctor 會回報缺少允許清單項目。
• Codex ACP 配接器會隨 acpx Plugin 暫存，並在可行時於本機啟動。
• Codex ACP 會使用隔離的 CODEX_HOME 執行；OpenClaw 只會從主機 Codex 設定複製受信任的專案項目並信任作用中的工作區，而將驗證、通知和 hooks 留在主機設定上。
• 其他目標執行框架配接器在你第一次使用時，可能仍會依需求以 npx 擷取。
• 該執行框架的供應商驗證仍必須存在於主機上。
• 如果主機沒有 npm 或網路存取權，首次執行的配接器擷取會失敗，直到快取已預熱或配接器以其他方式安裝為止。

ACP 會啟動真正的外部執行框架程序。OpenClaw 擁有路由、 背景任務狀態、傳遞、繫結和政策；執行框架擁有其供應商登入、 模型目錄、檔案系統行為和原生工具。

在怪罪 OpenClaw 之前，請確認：

• /acp doctor 回報已啟用且健康的後端。
• 設定允許清單時，目標 id 受到 acp.allowedAgents 允許。
• 執行框架命令可以在 Gateway 主機上啟動。
• 該執行框架的供應商驗證已存在（claude、codex、gemini、opencode、droid 等）。
• 所選模型存在於該執行框架中 - 模型 id 不能跨執行框架通用。
• 要求的 cwd 存在且可存取，或省略 cwd 並讓後端使用其預設值。
• 權限模式符合工作需求。非互動式工作階段無法點選原生權限提示，因此大量寫入/執行的編碼執行通常需要能夠無人值守繼續的 ACPX 權限設定檔。

• 產生會建立或恢復 ACP 執行階段工作階段，在 OpenClaw 工作階段儲存區記錄 ACP metadata，並且在執行由父項擁有時可能建立背景任務。
• 父項擁有的 ACP 工作階段會被視為背景工作，即使執行階段工作階段是持久的；完成和跨介面傳遞會透過父任務通知器進行，而不是像一般面向使用者的聊天工作階段那樣運作。
• 任務維護會關閉終端或孤立的父項擁有一次性 ACP 工作階段。持久 ACP 工作階段會在仍有作用中對話繫結時保留；沒有作用中繫結的過期持久工作階段會被關閉，避免在擁有任務完成或其任務記錄消失後被靜默恢復。
• 已繫結的後續訊息會直接傳送到 ACP 工作階段，直到繫結被關閉、取消聚焦、重設或過期。
• Gateway 命令會留在本機。/acp ...、/status 和 /unfocus 永遠不會作為一般提示文字傳送給已繫結的 ACP 執行框架。
• 後端支援取消時，cancel 會中止作用中的回合；它不會刪除繫結或工作階段 metadata。
• close 會從 OpenClaw 的角度結束 ACP 工作階段並移除繫結。如果執行框架支援恢復，它可能仍會保留自己的上游歷史。
• acpx Plugin 會在 close 後清理 OpenClaw 擁有的包裝器和配接器程序樹，並在 Gateway 啟動期間收割過期的 OpenClaw 擁有 ACPX 孤兒程序。
• 閒置的執行階段 worker 在 acp.runtime.ttlMinutes 後符合清理資格；已儲存的工作階段 metadata 仍可供 /acp sessions 使用。

當啟用時，應路由至原生 Codex Plugin 的自然語言觸發：

• 「將這個 Discord 頻道繫結到 Codex。」
• 「將這個聊天附加到 Codex 執行緒 <id>。」
• 「顯示 Codex 執行緒，然後繫結這一個。」

原生 Codex 對話綁定是預設的聊天控制路徑。 OpenClaw 動態工具仍透過 OpenClaw 執行，而 Codex 原生工具（例如 shell/apply-patch）則在 Codex 內執行。 對於 Codex 原生工具事件，OpenClaw 會注入每回合的原生 hook relay，讓 Plugin hook 可以封鎖 before_tool_call、觀察 after_tool_call，並透過 OpenClaw 核准路由 Codex PermissionRequest 事件。 Codex Stop hook 會轉送到 OpenClaw before_agent_finalize，Plugin 可在其中要求多一次 模型回合，然後 Codex 才完成其回答。relay 仍刻意保持 保守：它不會變更 Codex 原生工具 引數，也不會重寫 Codex 執行緒記錄。只有在你想要 ACP runtime/session 模型時， 才使用明確的 ACP。嵌入式 Codex 支援邊界記載於 Codex harness v1 支援合約。

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

應路由至 ACP runtime 的觸發條件：

• "以一次性 Claude Code ACP 工作階段執行這個，並摘要結果。"
• "在執行緒中使用 Gemini CLI 處理這項任務，然後將後續追蹤保留在同一個執行緒中。"
• "透過 ACP 在背景執行緒中執行 Codex。"

OpenClaw 會選擇 runtime: "acp"、解析 harness agentId， 在支援時綁定到目前對話或執行緒，並 將後續追蹤路由至該工作階段，直到關閉/過期為止。Codex 只有在 ACP/acpx 為明確指定， 或原生 Codex Plugin 不適用於所要求的操作時，才會走這條路徑。

對於 sessions_spawn，只有在 ACP 已啟用、請求者未被沙箱化，且 ACP runtime 後端已載入時，才會公告 runtime: "acp"。acp.dispatch.enabled=false 會暫停自動 ACP 執行緒分派，但不會隱藏或封鎖明確的 sessions_spawn({ runtime: "acp" }) 呼叫。它的目標是 ACP harness id，例如 codex、 claude、droid、gemini 或 opencode。除非來自 agents_list 的一般 OpenClaw 設定 agent id 中的項目已明確設定為 agents.list[].runtime.type="acp"， 否則不要傳入；請改用預設的 sub-agent runtime。當 OpenClaw agent 設定了 runtime.type="acp" 時，OpenClaw 會使用 runtime.acp.agent 作為底層 harness id。

• --bind here 和 --thread ... 互斥。
• --bind here 只適用於公告目前對話綁定能力的頻道；否則 OpenClaw 會回傳清楚的不支援訊息。綁定會在 Gateway 重新啟動後保留。
• 在 Discord 上，spawnSessions 會控管 --thread auto|here 的子執行緒建立 - 不控管 --bind here。
• 如果你在未指定 --cwd 的情況下產生到不同 ACP agent，OpenClaw 預設會繼承目標 agent 的工作區。缺少繼承路徑（ENOENT/ENOTDIR）會後援到後端預設值；其他存取錯誤（例如 EACCES）會顯示為產生錯誤。
• Gateway 管理命令會在已綁定對話中保持本機處理 - 即使一般後續文字路由到已綁定的 ACP 工作階段，/acp ... 命令仍由 OpenClaw 處理；只要該介面已啟用命令處理，/status 和 /unfocus 也會保持本機處理。

當頻道 adapter 啟用執行緒綁定時：

• OpenClaw 會將執行緒綁定到目標 ACP 工作階段。
• 該執行緒中的後續訊息會路由到已綁定的 ACP 工作階段。
• ACP 輸出會傳回同一個執行緒。
• 取消聚焦/關閉/封存/閒置逾時或最大年限過期會移除綁定。
• /acp close、/acp cancel、/acp status、/status 和 /unfocus 是 Gateway 命令，不是傳給 ACP harness 的提示。

執行緒綁定 ACP 所需的功能旗標：

• acp.enabled=true
• acp.dispatch.enabled 預設為開啟（設為 false 可暫停自動 ACP 執行緒分派；明確的 sessions_spawn({ runtime: "acp" }) 呼叫仍可運作）。
• 頻道 adapter 執行緒工作階段產生已啟用（預設：true）：
  • Discord：channels.discord.threadBindings.spawnSessions=true
  • Telegram：channels.telegram.threadBindings.spawnSessions=true

執行緒綁定支援依 adapter 而異。如果作用中的頻道 adapter 不支援執行緒綁定，OpenClaw 會回傳清楚的 不支援/無法使用訊息。

• 任何公開 session/thread 綁定能力的頻道 adapter。
• 目前內建支援：Discord 執行緒/頻道、Telegram 主題（群組/超級群組中的論壇主題與 DM 主題）。
• Plugin 頻道可透過相同的綁定介面新增支援。

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

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

已繫結對話中的後續訊息會直接路由到 ACP 工作階段，而 ACP 輸出會傳回同一個頻道／執行緒／主題。

OpenClaw 會傳送給框架的內容：

• 一般已繫結後續訊息會以提示文字傳送，只有在框架／後端支援時才會附加附件。
• /acp 管理命令和本機 Gateway 命令會在 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": "Continue where we left off - fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

常見使用情境：

• 將 Codex 工作階段從筆電交接到手機，告訴你的代理程式從你離開的地方繼續。
• 繼續你在 CLI 中互動式啟動、現在透過代理程式以無介面方式進行的編碼工作階段。
• 接續因 Gateway 重新啟動或閒置逾時而中斷的工作。

注意事項：

• resumeSessionId 只會在 runtime: "acp" 時套用；預設子代理程式執行階段會忽略這個僅限 ACP 的欄位。
• streamTo 只會在 runtime: "acp" 時套用；預設子代理程式執行階段會忽略這個僅限 ACP 的欄位。
• resumeSessionId 是主機本機 ACP／框架繼續 id，不是 OpenClaw 頻道工作階段鍵；OpenClaw 在派送前仍會檢查 ACP 衍生政策與目標代理程式政策，而 ACP 後端或框架負責載入該上游 id 的授權。
• resumeSessionId 會還原上游 ACP 對話歷史；thread 和 mode 仍會正常套用到你正在建立的新 OpenClaw 工作階段，因此 mode: "session" 仍需要 thread: true。
• 目標代理程式必須支援 session/load（Codex 和 Claude Code 都支援）。
• 如果找不到工作階段 id，衍生會以清楚錯誤失敗，不會默默退回到新工作階段。

Gateway 部署後，請執行即時端對端檢查，而不是信任單元測試：

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

將閘門維持在 mode: "run"，並略過 streamTo: "parent" - 執行緒綁定的 mode: "session" 與串流轉送路徑是各自獨立、 更完整的整合檢查。