Codex 子代理：并行委派的正确配法

子代理解决的真正问题是上下文污染

一个长会话最贵的资源不是 token，是主线程的上下文。它会先被日志、grep 结果、失败的测试输出塞满，然后开始忘掉你二十分钟前定的规则。官方文档把这两种现象叫 context pollution（上下文污染）和 context rot（上下文腐烂）。子代理的思路很直接：把产生海量中间输出的事情丢出去，主线程只收结论。

• Subagent workflow：父代理拆任务、分派、等待、合并的整体流程。
• Subagent：单独跑的一个代理，有自己的一套模型与工具调用。
• Agent thread：子代理对应的 thread，可以单独查看、单独 steer、单独停。

怎么让它真的去分身

多代理在当前版本的 CLI、App、IDE 里默认是开着的。但它不会读心：除了最高档的智能档位会主动委派，多数情况下你得明说要并行。三句话以内的指令就够用。

Spawn two agents: one reviews the migration scripts, one checks the rollback path.
Delegate this work in parallel, one agent per failing test file.
Use one agent per section of the spec, then merge the summaries into one list.

• 直接下指令：spawn two agents、delegate this work in parallel、use one agent per point。
• 写进 AGENTS.md 或一个 skill：让「这类任务必须拆成并行子代理」变成默认行为，不用每次重复。
• 靠智能档位：ChatGPT Work 侧多数档位仍要显式要求，最高档会自己判断并主动委派。

委派提示词要说清三件事

官方给的建议可以浓缩成三条：怎么分工、要不要等全部完成、每个子代理回什么样的摘要。缺哪一条，协调工作就会掉回你身上。

1. 01

   写清切法

   按风险类别切、按目录切、按失败用例切都可以，但要明确边界，避免两个子代理扫同一片区域。

2. 02

   写清等待策略

   是等全部结果齐了再统一汇总，还是先回来一个就先处理一个。前者适合出报告，后者适合抢时间。

3. 03

   写清交付格式

   要多少条、要不要文件路径和行号、要不要区分「确认的问题」和「可疑但没验证」。

4. 04

   写清只读还是可写

   只做分析的子代理明确写不要改文件，否则它可能顺手「修好」你正要自己改的地方。

用并行子代理审查这个分支，一共三个：
1) 安全风险，2) 测试缺口，3) 可维护性。
三个都只读，不要改文件。
各自最多返回 8 条，带文件路径与行号。
三个都跑完再汇总，按类别组织，不要按子代理组织。

内置代理与自定义代理

不配置也能用，因为有三个内置代理兜底。想做稳定的分工，就写自定义 agent：每个文件一个 TOML，放在项目里的 .codex/agents/ 或个人的 ~/.codex/agents/。

name = "pr_explorer"
description = "只读探索：定位改动范围、相关测试与历史提交"
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Stay in exploration mode. Do not edit files.
Report file paths, line numbers, and the tests that cover them.
If something is uncertain, say so instead of guessing.
"""

• 必填三字段：name、description、developer_instructions。名字是唯一标识，文件名不要求和它同名。
• 可选字段：model、model_reasoning_effort、model_reasoning_summary、model_verbosity。
• 自定义代理和内置代理重名时，自定义的优先。
• 这些字段不能覆盖：sandbox_mode、approval_policy、model_provider、mcp_servers、service tier。安全边界在父会话手里，不在 agent 文件里。

全局开关：并发上限与默认模型

子代理的全局行为在 config.toml 的 [agents] 表里调。最常改的是并发上限和默认模型：并发太高会互相抢文件、也会把额度烧快。

[agents]
enabled = true
max_concurrent_threads_per_session = 6
default_subagent_model = "gpt-6-luna"
default_subagent_reasoning_effort = "high"

• 解析顺序：spawn 时显式指定的值 → [agents] 里的默认值 → 父代理的 model 与 effort。
• 如果 spawn 或默认值只指定了模型、没给 effort，就用这个模型自己的默认 effort，不是父代理的。
• 旧配置里可能见到 max_threads，那是 max_concurrent_threads_per_session 的旧别名。

权限继承、审批与四个常见坑

子代理继承父会话的 sandbox 与 approval 设置，包括你通过 /permissions 或 --yolo 做的改动。这既是保护也是坑：父会话放得开，子代理也一样放得开；反过来，父会话卡得死，子代理会一路卡在审批上。

1. 并发写冲突：两个子代理改同一个文件时，后写的会覆盖前写的。写多的任务要么串行，要么给每个子代理划清目录。
2. 成本失控：每个子代理都是独立调用，并行四个可能等于四倍多的 token。先在小任务上量一次，再放开。
3. 等太久：把所有结果都等到齐，最慢的那个会拖住全部。可以让快的先返回、慢的单独收。
4. 看不见在跑什么：CLI 里用 /subagents 查看和切换 thread，App 看活动面板，IDE 看 background-agent 面板，别靠猜。

顺手还能做的事：直接让 Codex 去 steer 或停掉某个子代理，不用自己切过去操作。写任务时把「什么情况下停下来问我」也写进去，比事后发现它跑偏要省。

从单线程走到三代理的路径

别一上来就配五个代理。按下面顺序走，每一步都能验证收益是不是真的存在。

1. 01

   第一步：先量基线

   同一类任务用单代理跑一遍，记下耗时、你要介入几次、主线程上下文被吃掉多少。这是后面判断「并行值不值」的参照。

2. 02

   第二步：只并行读任务

   从代码库探索、测试 triage、文档总结这类只读任务开始，冲突风险最低，收益也最容易看见。

3. 03

   第三步：固化成自定义 agent

   某类子任务重复出现三次以上，就把它写成 .codex/agents/ 里的 TOML，把提示词固定下来。

4. 04

   第四步：再碰写任务

   写任务并行前先划清目录边界，并把并发上限压低一档，宁可慢一点也别处理合并冲突。

子代理和分支、worktree 常常一起用：并行改代码时给每个子代理一个独立工作目录，冲突就从「文件级」降到「合并级」。这部分见分支那篇。