Codex Multi-Agent V2 工程師指南：設定、角色設計、並行策略與踩雷清單

1. 先釐清產品邊界：CLI V2、API beta 與 App 平行工作不是同一件事

Codex Multi-Agent V2 是 Codex 執行環境內的子代理協作機制：主代理負責拆解、派工、等待、追問與整合，子代理各自保有工作脈絡。它和 Responses API 的 multi-agent beta 有相似的代理樹概念，但 API 另有 spawn_agent、send_message、followup_task、wait_agent、interrupt_agent 與 list_agents 等協作動作及 API 限制；Codex App 的多執行緒與 worktree 則是另一個更高層的平行工作介面。設計流程前要先確認你控制的是 CLI 設定、API 呼叫，還是 App 工作區，不能直接套用另一層的參數與限制。

2. 目前成熟度：0.145.0 標記穩定，但仍是 opt-in

OpenAI 在 2026 年 7 月 21 日發布 Codex CLI 0.145.0，將 Multi-Agent V2 標記為穩定，並加入可設定的子代理模型、推理強度、並行度、恢復後角色與更好的代理導覽。不過官方變更仍刻意維持預設關閉；這裡的 stable 代表實作與設定契約已跨過開發中階段，不代表所有使用者自動啟用，也不代表任何任務都會因增加代理而變快。導入前先升級到 0.145.0 或更新版本，並在固定任務集上驗證。

• 先確認 codex --version，再確認實際載入的 config.toml。
• 把單代理結果保存成基準，否則無法判斷多代理是否真的改善。
• 版本升級後重新驗證角色載入、resume、沙箱與併發限制。

3. 最小啟用設定：V2 行為與子代理預設值分開管理

目前設定 Schema 將 V2 的開關、每個工作階段最大執行緒數與等待逾時放在 features.multi_agent_v2；子代理預設模型與推理強度則放在 agents。舊式的 agents.max_threads 與 V2 並不等價，而且 Codex 原始碼會在 V2 啟用時拒絕同時設定 agents.max_threads。max_depth 只控制 V1，V2 會忽略。設定時應依目前安裝版本的官方 Schema 再確認，不要從舊文章複製片段。

4. 哪些任務值得拆：以依賴關係與可獨立驗證為判準

最適合平行化的是彼此依賴低、輸出可單獨驗證的工作，例如架構導覽、相依套件調查、測試缺口盤點、API 契約比對、文件查核、風險審查與不同模組的只讀分析。最不適合的是多個代理同時重構共享核心、修改同一份 migration、改同一組快照或依賴連續決策的除錯。官方文件也提醒，讀取密集任務通常容易擴展，寫入密集任務則容易產生衝突與協調成本。實務上可採「多個讀者、一個寫者」：探索者提交證據與建議，唯一 worker 整合修改。

5. 角色設計：把責任、邊界與完成證據寫進 TOML

Codex 內建 default、worker 與 explorer；團隊也可在 ~/.codex/agents 或專案的 .codex/agents 以 TOML 定義自訂角色，專案層設定適合納入版本控制。每個角色至少需要 name、description 與 developer_instructions，並可設定 model、model_reasoning_effort、sandbox_mode 等角色專屬配置。不要只寫「你是 reviewer」；應寫清楚可讀取的範圍、禁止修改的路徑、必跑的指令、輸出格式、引用證據的方法與停止條件。不同 Codex 表面對自訂角色的載入與命名呼叫能力可能不完全一致，工具型工作階段應先做小型驗證。

6. 模型與推理預算：把預設值視為成本政策

V2 可在 agents 設定預設子代理模型與推理強度，也可在角色檔或特定 spawn 時覆寫。不要讓每個子代理都使用最高推理強度：先依任務風險分級，限制最大併發，並追蹤總 token、總工具呼叫與人工修正時間。較快模型可處理檔案分類、關鍵字掃描與初步查核；高風險整合、複雜除錯或最終審查再使用較強模型。這是工程成本分層策略，不是任何模型的普遍排名。牆鐘時間下降但總成本倍增，不一定是成功。

7. 派工提示必須像介面契約，而不是聊天邀請

一個可重複的子代理任務至少要包含五項：目標、可用輸入、責任邊界、交付格式與完成條件。主代理還要指定如何處理不確定性：缺少證據時回報未知，不要自行擴大範圍。這能降低重複研究、越界修改與無法合併的泛泛結論。對工程工作而言，最有用的派工內容不是角色形容詞，而是明確路徑、允許的命令、禁止事項與輸出 Schema。

8. 執行生命週期：主代理擁有控制權，子執行緒不是第二個聊天室

V2 的子代理執行緒由父執行緒控制，TUI 允許透過 /agent 導覽與檢視，但父控制的子執行緒是唯讀，直接向該執行緒輸入會被拒絕。需要追加任務、修正方向或中斷時，應回到主代理，由主代理傳送訊息、追問或停止。這個設計能保留單一協調者與可追溯的決策鏈。0.145.0 前後也補強恢復工作階段後的懶載入與角色還原；若 resume 後出現角色、模型、工作目錄或權限不一致，先升級並確認使用的是 V2。

9. 權限與沙箱：代理數量不會創造新的授權邊界

子代理通常會在父工作階段的權限與沙箱脈絡內執行，因此不能假設「子代理」天然是低權限。把 explorer、dependency auditor 與 docs researcher 設為 read-only；只有指定 worker 能寫入，且外部網路、憑證、部署、資料庫 migration 與通知發送都應維持最小權限與人工核准。對含病患、客戶或生產資料的專案，測試資料隔離、短效憑證、命令軌跡與可回滾性必須先於擴大併發。

10. 一個可落地的 PR 審查拓撲

主代理先取得 diff 與驗收條件，再平行派出三個只讀角色：code-path explorer 追蹤受影響呼叫鏈；test reviewer 檢查分支、錯誤處理與回歸覆蓋；docs/security reviewer 查核公開契約、權限與敏感資料。三者回傳檔案位置、嚴重度、證據與建議後，主代理去重並決定是否交給單一 worker 修正。worker 完成後執行目標測試與完整必要檢查，最後由一個獨立 reviewer 只看最終 diff。這比讓四個代理同時修檔更容易稽核，也能量化每個角色的實際貢獻。

11. 常見失敗模式與診斷順序

沒有產生子代理時，依序確認 Codex 版本、features.multi_agent_v2.enabled、agents.enabled、提示是否明確要求委派，以及專案指令是否限制主動 delegation。代理互相覆蓋修改時，先停掉多寫者模式，依檔案或模組重新分區。結果重複時，縮窄每個角色的問題與輸出 Schema。成本失控時，降低併發、使用較快模型處理掃描、限制檔案範圍並設定停止條件。無法直接在父控制的子執行緒輸入通常是設計行為；角色或模型覆寫失敗時，應檢查實際表面是否支援專案自訂角色、角色 TOML 是否有效，以及設定層級是否被其他 config 覆蓋。

12. 導入與評估：先做受控實驗，再變成團隊預設

選 20 至 30 個可重跑的真實任務，建立單代理基準與 V2 實驗組，固定模型、版本、權限、資料與驗收腳本。至少記錄成功率、牆鐘時間、總 token 或費用、工具錯誤、重複發現、檔案衝突、人工修正分鐘數、測試新增品質與缺陷逃逸率。只有在品質不下降、人工負擔可控且總成本符合目標時，才逐步提高併發或放寬寫入範圍。把 .codex/agents、AGENTS.md、測試命令與評估資料一起版本化，讓 Multi-Agent V2 成為可治理的工程系統，而不是依賴偶然提示的展示功能。