ACP 代理程式

• 如果設定了 plugins.allow，它就是限制性的外掛清單，且必須包含 acpx；否則已安裝的 ACP 後端會被刻意阻擋，且 /acp doctor 會回報缺少 allowlist 項目。
• Codex ACP adapter 會隨 acpx 外掛一起 staged，並在可能時於本機啟動。
• Codex ACP 會使用隔離的 CODEX_HOME 執行；OpenClaw 會從主機 Codex config 複製受信任的專案項目，以及安全的模型/供應商路由 config，而 auth、notifications 與 hooks 會留在主機 config 上。
• 其他目標 harness adapter 可能仍會在你第一次使用時，依需求透過 npx 擷取。
• 該 harness 的 vendor auth 仍必須存在於主機上。
• 如果主機沒有 npm 或網路存取權，首次執行 adapter 擷取會失敗，直到 cache 預先暖機，或以其他方式安裝 adapter。

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

在責怪 OpenClaw 之前，請確認：

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

• Spawn 會建立或恢復 ACP 執行階段工作階段，在 OpenClaw 工作階段儲存區記錄 ACP metadata，並可能在該執行屬於父項擁有時建立背景任務。
• 父項擁有的 ACP 工作階段會被視為背景工作，即使執行階段工作階段是 persistent；完成與跨介面遞送會透過父任務 notifier，而不是像一般面向使用者的聊天工作階段那樣運作。
• 任務維護會關閉 terminal 或孤立的父項擁有 one-shot ACP 工作階段。當仍存在作用中的對話綁定時，persistent ACP 工作階段會被保留；沒有作用中綁定的 stale persistent 工作階段會被關閉，避免在擁有任務完成或其任務記錄消失後被靜默恢復。
• 已綁定的 follow-up 訊息會直接傳送到 ACP 工作階段，直到綁定被關閉、取消聚焦、重設或過期。
• Gateway 命令會保持本機處理。/acp ...、/status 與 /unfocus 絕不會作為一般 prompt 文字傳送給已綁定的 ACP harness。
• 後端支援取消時，cancel 會中止作用中的回合；它不會刪除綁定或工作階段 metadata。
• 從 OpenClaw 的角度，close 會結束 ACP 工作階段並移除綁定。如果 harness 支援 resume，它仍可能保留自己的上游歷程。
• acpx 外掛會在 close 後清理 OpenClaw 擁有的 wrapper 與 adapter 程序樹，並在 Gateway 啟動期間回收 stale 的 OpenClaw 擁有 ACPX orphan。
• 閒置執行階段 worker 在 acp.runtime.ttlMinutes 後符合清理資格；儲存的工作階段 metadata 仍可供 /acp sessions 使用。

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

• 「將此 Discord channel 綁定到 Codex。」
• 「將此聊天附加到 Codex thread <id>。」
• 「顯示 Codex threads，然後綁定這一個。」

原生 Codex 對話繫結是預設的聊天控制路徑。 OpenClaw 動態工具仍透過 OpenClaw 執行，而 Codex 原生工具（例如 shell/apply-patch）則在 Codex 內執行。 對於 Codex 原生工具事件，OpenClaw 會注入每回合的原生 鉤子轉送，讓外掛鉤子可以阻擋 before_tool_call、觀察 after_tool_call，並將 Codex PermissionRequest 事件 透過 OpenClaw 核准流程路由。Codex Stop 鉤子會轉送到 OpenClaw before_agent_finalize，外掛可在其中要求再進行一次 模型傳遞，然後 Codex 才完成其回答。此轉送機制刻意保持保守： 它不會變更 Codex 原生工具 引數，也不會重寫 Codex 執行緒記錄。只有在需要 ACP 執行階段/工作階段模型時 才使用明確的 ACP。嵌入式 Codex 支援邊界記錄於 Codex harness v1 支援合約。

• 舊版 Codex 模型參照 - doctor 修復的舊版 Codex OAuth/訂閱模型路由。
• openai/* - 用於 OpenAI 代理回合的原生 Codex 應用伺服器嵌入式執行階段。
• /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[].runtime.type="acp" 明確設定， 否則不要傳入來自 agents_list 的一般 OpenClaw 設定代理 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: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

執行緒繫結支援依轉接器而異。如果目前的頻道 轉接器不支援執行緒繫結，OpenClaw 會回傳清楚的 不支援/不可用訊息。

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

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

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

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

OpenClaw 傳送給 harness 的內容：

• 一般已繫結後續訊息會作為提示文字傳送；只有在 harness/後端支援時才會附加附件。
• /acp 管理指令和本機 Gateway 指令會在 ACP 派送前被攔截。
• 執行階段產生的完成事件會依目標具現化。OpenClaw 代理會取得 OpenClaw 的內部執行階段內容封套；外部 ACP harness 會取得包含子結果與指示的純提示。原始 <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> 封套絕不應傳送到外部 harness，或作為 ACP 使用者逐字稿文字持久化。
• ACP 逐字稿項目會使用使用者可見的觸發文字或純完成提示。內部事件中繼資料在可能時會在 OpenClaw 中保持結構化，且不會被視為使用者撰寫的聊天內容。

由另一個代理執行產生的一次性 ACP 工作階段是背景子項，類似子代理：

• 父層使用 sessions_spawn({ runtime: "acp", mode: "run" }) 請求工作。
• 子項會在自己的 ACP harness 工作階段中執行。
• 子回合會在原生子代理產生所使用的同一條背景通道上執行，因此緩慢的 ACP harness 不會阻塞不相關的主工作階段工作。
• 完成會透過工作完成公告路徑回報。OpenClaw 會在傳送到外部 harness 前，將內部完成中繼資料轉換為純 ACP 提示，因此 harness 不會看到 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 工作階段從筆電交接到手機 - 告訴你的代理從上次中斷處接續。
• 繼續你先前在命令列介面中互動式啟動的編碼工作階段，現在透過你的代理以無頭模式執行。
• 接續因閘道重新啟動或閒置逾時而中斷的工作。

注意事項：

• resumeSessionId 只在 runtime: "acp" 時適用；預設子代理執行階段會忽略這個僅限 ACP 的欄位。
• streamTo 只在 runtime: "acp" 時適用；預設子代理執行階段會忽略這個僅限 ACP 的欄位。
• resumeSessionId 是主機本機的 ACP/harness 恢復 id，不是 OpenClaw 頻道工作階段金鑰；OpenClaw 在分派前仍會檢查 ACP 產生政策和目標代理政策，而 ACP 後端或 harness 負責載入該上游 id 的授權。
• 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" 和串流轉送路徑屬於 另外更完整的整合檢查。