Codex Subagents 并行协作实战

嘿，朋友！今天咱们聊聊 Codex 的 Subagents——就是把一个大活儿拆成几个小活儿，让多个 agent 同时干。我第一次用的时候特兴奋，一口气起了五个 agent 去审查同一个 PR，结果三个 agent 在同一个文件里打架，另外两个得出了完全相反的结论，最后我花的时间比单干还多一倍。所以这玩意儿用对了是真香，用错了就是烧钱机器。

Subagents 的核心价值就一句话：把互相不沾边的任务并行掉。要是你把同一个模糊需求扔给一堆 agent，它们会各自为战——重复搜索同一段代码、抢同一个文件、给出互相矛盾的结论，不仅额度哗哗地走，你整合的时候更想哭。

先判断能不能并行

先说哪些场景合适：

• 同一个 PR，分别做安全审查、测试审查、性能审查、兼容性审查——证据源一样但关注点不同；
• 好几个互不依赖的模块，各自做只读调研；
• 大批量记录处理，按行或者按文件拆开各干各的；
• 前后端、文档在接口契约拍板之后，各写各的；
• 多个候选技术方案，各自独立搭实验验证。

反过来，这些情况别硬拆：

• 需求和接口还在变，拆了也是白拆；
• 几个任务都要改同一个核心文件——那等着冲突吧；
• 下一步强依赖上一步的结果，没法并行；
• 涉及生产环境操作或者不可逆的决策；
• 纯粹觉得「多几个模型更聪明」，但根本找不到拆分边界。

说到拆分边界，我踩过一个典型的坑：让两个 agent 同时优化同一个模块的性能，一个改算法、一个改缓存策略，结果它们各自生成了一个 patch，合在一起直接编译不过。从那以后我的铁律就是——改同一个文件的任务绝不并行。

最稳妥的第一次并行任务：只读审查

如果你还没玩过 Subagents，我强烈建议从只读审查开始。零风险，纯收益。

并行审查当前分支相对 main 的变化。

请启动三个 Subagents：
1. 安全审查：只找授权绕过、秘密泄漏和不安全外部输入；
2. 正确性审查：只找真实逻辑错误、竞态和兼容性回归；
3. 测试审查：只找关键行为没有覆盖或测试无效的地方。

全部使用只读权限。等待三者完成后，由主任务去重并按 P0-P3 汇总。每条发现要有文件、触发条件和影响。不要修改文件。

这类任务的妙处在于：输入共享但输出各管各的，没有文件冲突，是验证并行价值的最佳试金石。

实现任务必须先冻结契约

好，到了真正要写代码的环节了。比如前后端并行开发，千万不能上来就各干各的。你得先当一回「接口警察」，把下面这些东西白纸黑字定死：

• API 路径和方法；
• 请求/响应 schema；
• 错误码；
• 权限；
• 数据上限；
• 测试 fixture；
• 文件所有权。

契约落地之后再分配：

后端 agent 只修改 server/orders/**；前端 agent 只修改 web/orders/**。共享契约文件只读。两边不得提交或推送。完成后返回修改文件、验证命令和未决问题，由主任务统一集成。

我有个项目就是偷懒跳过了这步，心想「反正约定俗成了」，结果前端和后端 agent 各自理解错了两个字段的类型，联调的时候才发现——浪费了整整一轮额度。从那以后我每次必先花五分钟写契约，这五分钟能省你后面五十分钟。

内置角色与自定义角色

Codex 自带几个常用角色：通用的 default、干活的 worker、只读探索的 explorer。够用，但如果你想玩出花样，可以在 ~/.codex/agents/（用户级）或 .codex/agents/（项目级）定义自己的 agent TOML。

项目级 .codex/agents/reviewer.toml 示例：

name = "reviewer"
description = "Read-only reviewer for correctness, security, and missing tests."
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Lead with concrete, reproducible findings.
Ignore style-only preferences unless they hide a real bug.
Never modify files.
"""
nickname_candidates = ["Atlas", "Delta", "Echo"]

一个小贴士：不指定模型的话会继承父任务的模型，能减少版本漂移的烦恼。角色定义要窄而精，别搞出十个职责重叠的「专家」——那跟没拆一样。

控制并行规模

在 .codex/config.toml 里设：

[agents]
max_threads = 4
max_depth = 1

max_threads 管并发线程数，max_depth 管 agent 能不能继续往下派生子 agent。我的建议是深度就定在 1，别让 agent 生 agent——递归扇出会让成本和不可控性指数级膨胀。你想想，一个 agent 起三个子 agent，每个子 agent 又起三个，一眨眼就九个了，额度账单那叫一个刺激。

给每个 agent 足够但最小的上下文

子任务的描述别偷懒，至少得包含这些：

• 目标和输出格式；
• 可读/可写的范围；
• 已冻结的接口；
• 验证命令；
• 不能干的事（外部操作黑名单）；
• 返回给主任务的摘要结构。

另外，别让每个 agent 都去扫描整个仓库——又慢又浪费。我的习惯是先让一个 explorer 跑一遍，把关键路径梳理出来，再把结果和目标文件精准喂给干活的 agent。这样每个 agent 只看到它该看的，聚焦又省钱。

主任务的职责不能外包

这一点太重要了，我得单独说。主任务不是甩手掌柜，外包出去的是执行，不是责任。主任务必须亲自做这些：

1. 检查子任务之间有没有重叠；
2. 等待所有必要结果到位；
3. 对互相矛盾的结论重新取证；
4. 去重和排序；
5. 审查完整的 Git diff；
6. 跑集成和端到端验证；
7. 报告哪些子任务没完成或失败了。

记住一句话：多个 agent 都说「通过」，不等于整体真能构建通过。 我以前犯过这个错，三个 agent 各自返回「测试通过」，我一合代码直接挂了——因为没人跑集成测试。从那以后，集成验证我永远留在主任务自己手里。

踩坑记录：失败处理

agent 卡住不动

先别急着杀，检查是不是缺依赖、权限不够或者输入不完整。缩小任务范围再试一次，往往就好了。不要无脑加超时时间——等不出来的。

两个 agent 改了同一个文件

立刻停下来，别让它们自动合并。你先确定哪个版本是主版本，手动比对真实差异，然后重新划清文件所有权。让 agent 自动覆盖另一个 agent 的工作等于花钱买 bug。

结论互相打架

让主任务要求双方各自提供调用链、测试用例或者官方文档来源，由证据说了算。别让它们「商量商量」——商量出来的往往是折中方案，不一定是正确的。

成本高收益低

缩小 agent 数量，只对最耗时且互相独立的调查任务开并行。小任务单 agent 反而更快——别为了并行而并行。

完成门槛

发车之前，拿这个 checklist 过一遍：

• [ ] 并行子任务彼此独立。
• [ ] 每个 agent 有明确权限、文件和输出边界。
• [ ] 接口与合并顺序在开始前确定。
• [ ] 主任务去重、解决冲突并运行整体验证。
• [ ] 使用并行确实缩短关键路径，而不是重复劳动。

下一步

需要把 Codex 嵌入自己的服务或工具时，继续学习 Codex SDK 与 App Server。

事实来源

• OpenAI：Subagents