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 執行階段工作階段、在 OpenClaw 工作階段儲存區記錄 ACP 中繼資料，並可能在執行由父項擁有時建立背景任務。
• 即使執行階段工作階段是持久的，由父項擁有的 ACP 工作階段仍會視為背景工作；完成通知與跨介面傳遞會透過父項任務通知器進行，而不會像一般面向使用者的聊天工作階段般運作。
• 任務維護會關閉已終止或已成為孤立項目、由父項擁有的一次性 ACP 工作階段。只要仍有作用中的對話繫結，就會保留持久 ACP 工作階段；若過時的持久工作階段沒有作用中繫結，則會將其關閉，避免在所屬任務完成或其任務記錄消失後遭到無聲恢復。
• 已繫結的後續訊息會直接傳送至 ACP 工作階段，直到繫結被關閉、取消聚焦、重設或過期。
• 閘道命令會保留在本機處理。/acp ...、/status 和 /unfocus 絕不會作為一般提示文字傳送至已繫結的 ACP 執行框架。
• 後端支援取消時，cancel 會中止作用中的回合；它不會刪除繫結或工作階段中繼資料。
• 從 OpenClaw 的角度來看，close 會結束 ACP 工作階段並移除繫結。如果執行框架支援恢復，它仍可能保留自己的上游歷程記錄。
• close 後，acpx 外掛會清理由 OpenClaw 擁有的包裝器和轉接器程序樹，並在閘道啟動期間回收過時且由 OpenClaw 擁有的 ACPX 孤立程序。
• 閒置執行階段工作程序會在 acp.runtime.ttlMinutes 後符合清理資格；已儲存的工作階段中繼資料仍可供 /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 CLI 執行此工作，然後讓後續訊息維持在同一執行緒中。」
• 「透過 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" }) 呼叫。它以 codex、claude、droid、 gemini 或 opencode 等 ACP 控制框架 ID 為目標。除非 agents_list 中的項目已明確設定 agents.list[].runtime.type="acp"，否則請勿傳入一般的 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 主題（群組／超級群組中的論壇主題與私訊主題）。
• 外掛頻道可透過相同的綁定介面新增支援。

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

• /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 設定下），此路徑仍會啟用。

OpenClaw 只有在請求者是其自行擁有、由父工作階段管理的一次性 ACP 子工作階段之父工作階段時，才會略過 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／控管程式恢復識別碼，不是 OpenClaw 頻道工作階段金鑰；OpenClaw 在分派前仍會檢查 ACP 產生原則與目標代理程式原則，而載入該上游識別碼的授權則由 ACP 後端或控管程式負責。
• resumeSessionId 會還原上游 ACP 對話記錄；thread 與 mode 仍會正常套用至你正在建立的新 OpenClaw 工作階段，因此 mode: "session" 仍要求 thread: true。
• 目標代理程式必須支援 session/load（Codex 與 Claude Code 均支援）。
• 如果找不到工作階段識別碼，產生作業會失敗並顯示明確錯誤，不會無提示地退回建立新工作階段。

部署閘道後，應執行即時端對端檢查，而非僅信任單元測試：

1. 在目標主機上確認已部署的閘道版本與提交。
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" 與串流轉送路徑屬於另外兩項更完整的整合測試。