用 Subagents 拆分任務

Subagents 用來把複雜任務拆給多個專門 agent 並行處理，再由主 agent 彙總結果。它適合高度並行的探索、審查和事實核驗，不適合小任務或強序列任務。

Subagents 不是越多越強。每個 subagent 都會消耗模型和工具資源，也會增加上下文、審批和寫入衝突成本。

當前 Codex releases 預設啟用 subagent workflows，但 Codex 只會在你明確要求時 spawn subagents。官方文件也強調：每個 subagent 都會獨立做模型和工具工作，因此會比單 agent 消耗更多 tokens。

Subagents

檢視官方 subagents 配置和使用說明。

Skills vs Subagents

區分流程複用和任務拆分。

Team production

多 agent 進入團隊流程前先明確邊界和治理。

什麼時候該拆

flowchart TD
    Task["任務來了"]
    Independent{"子問題是否獨立?"}
    Outputs{"輸出是否能彙總?"}
    Write{"是否會寫同一批檔案?"}
    Use["適合 subagents"]
    Single["保持單 agent"]

    Task --> Independent
    Independent -->|否| Single
    Independent -->|是| Outputs
    Outputs -->|否| Single
    Outputs -->|是| Write
    Write -->|會衝突| Single
    Write -->|不會| Use

適合拆：

PR 同時做安全、測試、文件和架構審查。
大型程式碼庫探索多個模組。
一個 agent 查官方文件，另一個讀程式碼。
多個只讀維度可以並行。

不適合拆：

單檔案修改。
小 bug。
強依賴同一段上下文的除錯。
多個 worker 會改同一檔案。
non-interactive 環境無法處理審批。

內建角色怎麼用

Codex 內建三類 agents：

agent	用途	推薦邊界
`explorer`	read-heavy codebase exploration	只讀查證、回答具體程式碼庫問題。
`worker`	implementation and fixes	執行明確修改，必須有檔案 ownership。
`default`	general-purpose fallback	無特定角色時兜底。

新手建議先用只讀 explorer。需要寫檔案時，只給一個 worker 明確寫入範圍。不要讓多個 worker 同時改同一批檔案。

CLI 中可以用 /agent 切換 active agent thread，檢視或繼續某個 subagent 的上下文。任務結束後，讓主 agent close completed agent threads，避免後臺執行緒長期佔用上下文和狀態。

寫給 subagent 的任務要窄

好的 subagent 任務應該包含：

它負責什麼。
它不能碰什麼。
輸入範圍。
輸出格式。
是否只讀。
是否允許呼叫外部工具。

示例：

只读检查 PR diff 中的权限和数据泄露风险。
不要修改文件。
输出按严重程度排序的 findings，每条包含文件、证据和建议。

任務越窄，主 agent 越容易彙總。

許可權和審批

Subagents 的許可權邊界不能忽略：

它們可能繼承當前 sandbox。
它們可能觸發自己的審批請求。
它們可能讀取不同上下文。
它們可能產生寫入衝突。

建議：

初期全部只讀。
寫入任務只交給一個 worker。
明確檔案 ownership。
非互動任務避免需要審批的 subagent 動作。
結束後彙總每個 subagent 做了什麼。

官方行為要記住兩點：

Subagents inherit 當前 sandbox policy。
互動式 CLI 中，inactive thread 也可能彈出 approval request；approval overlay 會顯示來源 thread。

非互動流程中，如果某個動作需要新的 approval 但無法彈出視窗，該動作會失敗並把錯誤返回給 parent workflow。因此 CI、批處理、自動化裡更適合只讀 subagents 或預先收窄許可權邊界。

自定義 agents

當內建角色不夠用時，可以新增 custom agent：

~/.codex/agents/reviewer.toml
.codex/agents/reviewer.toml

每個 standalone TOML 檔案定義一個 agent，至少包含：

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""

可以額外設定 model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config 等配置。全域性併發和深度放在 [agents]：

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

預設 agents.max_threads 是 6，agents.max_depth 是 1。不要輕易提高 depth，遞迴拆分會快速增加成本、等待時間和不可預測性。

常見坑

為了並行而並行。
子任務沒有明確交付物。
多個 worker 改同一檔案。
子結果都是自然語言，無法彙總。
沒有說明哪個結果是事實、哪個是推斷。
忘記 token 和工具呼叫成本。
讓 subagent 繼續無限拆分。

Subagents 的價值來自清晰分工，而不是數量。

驗收標準

使用 subagents 後，應能回答：

每個 subagent 負責什麼。
哪些只讀，哪些可寫。
輸出如何進入主結論。
是否真的更快或更全面。
是否產生衝突或重複判斷。
成本是否值得。

不能回答這些問題，就回到單 agent。