ACP 代理程式

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

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

在歸咎於 OpenClaw 之前，請確認：

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

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

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

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

• "以一次性 Claude Code ACP 工作階段執行此項，並摘要結果。"
• "在一個執行緒中使用 Gemini CLI 完成此工作，然後將後續對話保留在同一個執行緒中。"
• "透過 ACP 在背景執行緒中執行 Codex。"

OpenClaw 會選擇 runtime: "acp"、解析 harness agentId、 在支援時繫結到目前對話或執行緒，並將後續對話路由到該工作階段，直到關閉/到期為止。 只有在明確指定 ACP/acpx，或原生 Codex Plugin 無法用於所要求操作時，Codex 才會遵循此路徑。

對於 sessions_spawn，只有在 ACP 已啟用、請求者未受 sandbox 限制，且已載入 ACP 執行階段 後端時，才會公告 runtime: "acp"。acp.dispatch.enabled=false 會暫停自動 ACP 執行緒派送，但不會隱藏或封鎖明確的 sessions_spawn({ runtime: "acp" }) 呼叫。它的目標是 ACP harness ID，例如 codex、 claude、droid、gemini 或 opencode。除非該項目已明確以 agents.list[].runtime.type="acp" 設定， 否則不要從 agents_list 傳入一般 OpenClaw 設定 agent ID；否則請使用預設子代理執行階段。當 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 也會保持本機處理。

當頻道介面卡啟用執行緒繫結時：

• OpenClaw 會將執行緒繫結到目標 ACP 工作階段。
• 該執行緒中的後續訊息會路由到已繫結 ACP 工作階段。
• ACP 輸出會傳回同一個執行緒。
• Unfocus/close/archive/idle-timeout 或 max-age 到期會移除繫結。
• /acp close、/acp cancel、/acp status、/status 和 /unfocus 是 Gateway 命令，不是傳給 ACP harness 的提示。

執行緒繫結 ACP 所需的功能旗標：

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

執行緒繫結支援依介面卡而定。如果作用中的頻道 介面卡不支援執行緒繫結，OpenClaw 會傳回清楚的 不支援/不可用訊息。

• 任何公開工作階段/執行緒繫結能力的頻道介面卡。
• 目前內建支援：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 版本與 commit。
2. 開啟通往 live agent 的暫時 ACPX bridge session。
3. 要求該 agent 以 runtime: "acp"、agentId: "codex"、mode: "run"，以及任務 Reply with exactly LIVE-ACP-SPAWN-OK 呼叫 sessions_spawn。
4. 驗證 accepted=yes、真實的 childSessionKey，且沒有 validator error。
5. 清理暫時 bridge session。

將 gate 保持在 mode: "run"，並略過 streamTo: "parent" - 綁定 thread 的 mode: "session" 與 stream-relay 路徑是獨立的 更完整整合檢查。