别再让 Codex 一个人包打天下：多 Agent 协同实战

一个横跨前端、后端和数据库的需求突然插进来：新增接口、调整页面、补单元测试，还要检查权限风险。

如果把整件事一次性交给 Codex，它需要先读项目结构，再定位业务逻辑，然后修改代码、补测试、运行构建，最后还要审查自己的改动。

任务不是不能完成，问题是所有探索记录、错误日志、测试输出和修改细节都挤在同一个上下文里。对话越来越长，真正重要的需求约束反而被埋了。

这和现实中的团队一样。一个人既负责需求分析，又写前端、改后端、测功能、审代码，表面上没有沟通成本，实际却没有人交叉检查。忙到最后，功能可能上线了，隐藏的问题也一起上线了。

Codex 的多 Agent 协作解决的正是这个问题：主 Agent 负责拆任务、定边界、收结果和做验收，子 Agent 分别处理可以独立推进的工作。

真正的重点不是同时启动多少个 Agent，而是哪些任务应该并行，哪些任务必须等上一步结束。

Codex 多 Agent，不是把同一句话问三遍

根据当前官方 OpenAI 文档，Codex 支持子 Agent 工作流。主 Agent 可以启动多个专门的子 Agent，让它们并行进行代码探索、测试、排障、审查或摘要，再把结果汇总到主对话中。

子 Agent 的工作过程位于独立线程中。在支持的 Codex 桌面端、CLI 和 IDE 扩展中，可以查看这些子线程的进度和结果。

这种设计首先解决的是上下文污染。

例如排查一次构建失败，可能产生几百行依赖日志；分析一个大型项目，可能需要打开几十个文件。如果所有中间输出都进入主对话，需求、约束和关键决策很容易被噪声淹没。

把探索工作交给子 Agent 后，主 Agent 不需要保留全部原始过程，只接收经过整理的结论：

主 Agent
├── 架构分析 Agent：返回相关模块、调用链和风险点
├── 测试 Agent：返回失败用例、复现步骤和日志摘要
└── 审查 Agent：返回安全、兼容性和可维护性问题

主 Agent 保留的是“应该做什么”和“最后是否合格”，子 Agent 承担的是“去哪里找证据”和“如何完成具体任务”。

但子 Agent 并不是免费的并行计算。每个子 Agent 都会单独使用模型和工具，因此通常会消耗更多 token。任务拆得过细，协调成本甚至可能超过实际工作量。

多 Agent 的价值不在于多叫几个人，而在于让正确的人，在正确的时间，只负责正确的事。

一个写稿、两个审稿，为什么不能同时启动

假设我要用 Codex 完成一篇技术文章，分工如下：

• 写稿 Agent：根据主题和资料完成初稿。
• 技术审稿 Agent：检查事实、命令、配置和版本边界。
• 编辑审稿 Agent：检查标题、结构、重复内容和阅读节奏。
• 主 Agent：汇总审稿意见，处理冲突并交付终稿。

这里虽然有三个子 Agent，却不能一开始就把三个全部并行启动。

两个审稿 Agent 都依赖写稿 Agent 的初稿。如果初稿还不存在，审稿 Agent 只能猜测文章可能出现什么问题，得到的结论没有实际价值。

正确的工作流应该是：

用户提出目标
      ↓
主 Agent 明确要求和验收标准
      ↓
写稿 Agent 完成初稿
      ↓
等待初稿返回
      ↓
┌──────────────┬──────────────┐
│ 技术审稿 Agent │ 编辑审稿 Agent │
└──────────────┴──────────────┘
      ↓ 两者并行返回
主 Agent 合并意见、修改并验收
      ↓
交付终稿

这叫“分阶段并行”。

第一阶段只有写稿任务；第二阶段的两项审查互不依赖，可以并行。既利用了并发，又没有破坏任务依赖关系。

在 Codex 中，可以直接这样描述：

请使用子 Agent 完成这篇文章。

第一阶段：
启动一个写稿 Agent，根据给定主题和资料完成完整初稿。
等待它完成后再进入下一阶段。

第二阶段：
并行启动两个审稿 Agent。

技术审稿 Agent 负责检查：
1. 技术事实是否准确；
2. 命令和配置是否真实可用；
3. 是否混淆产品能力与当前会话限制；
4. 是否遗漏权限、成本和生产风险。

编辑审稿 Agent 负责检查：
1. 标题是否兑现正文承诺；
2. 结构是否自然；
3. 是否存在重复和空话；
4. 案例是否完整；
5. 是否适合微信公众号阅读。

等待两个审稿 Agent 全部完成。
最后由主 Agent 汇总意见、解决冲突、修改初稿并交付终稿。
不要把未经采纳的审稿意见直接拼进文章。

这个提示有四个关键点：明确角色、说明依赖、要求等待、规定返回内容。

只说“多开几个 Agent 帮我看看”，主 Agent 很难判断应该怎样分工，也无法知道什么时候可以结束。

写代码时，怎么拆才不会互相踩文件

文章审稿主要是只读工作，并行风险较低。代码开发则复杂得多，因为多个 Agent 可能共享同一个工作区。

假设一个需求同时涉及用户接口、管理页面和测试，可以这样分：

Agent A：只分析现有架构，不修改文件
Agent B：修改后端用户接口
Agent C：补充接口测试
主 Agent：整合改动、解决冲突并运行验证

这种分法看起来合理，但仍然有一个问题：如果后端 Agent 和测试 Agent 同时修改同一份测试配置，或者测试 Agent 根据尚未稳定的接口编写用例，就可能出现冲突和返工。

更稳妥的方式是按依赖拆成两个阶段。

先让只读分析 Agent 定位调用链、数据结构、测试入口和可能涉及的文件。主 Agent确认边界后，再把互不重叠的实现任务并行分配出去。

例如：

第一阶段：
- Agent A 只读分析后端入口、数据库访问和现有测试。
- 不允许修改任何文件。
- 返回建议修改的文件、接口契约和风险点。

第二阶段：
- Agent B 负责后端实现，只修改 server/ 目录。
- Agent C 负责测试，只修改 tests/ 目录。
- 两个 Agent 不得修改共享配置。

第三阶段：
- 主 Agent 检查差异、运行测试、处理失败并完成验收。

如果两个任务必须修改同一个核心文件，就不要为了追求“并行”强行拆开。让一个 Agent 负责实现，另一个 Agent 等实现完成后做审查，往更可靠。

官方文档也建议优先把读多写少的探索、测试、分类、日志分析和审阅交给并行 Agent。多个 Agent 同时进行大量代码修改，会增加文件冲突和协调成本。

下面用一个脱敏后的典型场景说明

以下项目名称、文件数量、耗时和测试数据均为示例，用于说明协作流程，不对应任何真实企业或客户。

某内部管理系统需要增加“批量禁用过期账号”功能。需求涉及权限校验、批量数据库更新、审计日志和前端确认弹窗。

初始项目包含约 480 个源文件，完整测试耗时约 18 分钟。单 Agent 第一次尝试时同时读取了路由、服务层、数据访问层、权限模块和前端页面，随后直接开始修改。

改动完成后，基础测试通过，但代码审查发现两个问题：批量接口没有限制单次账号数量，审计日志也只记录了操作人，没有记录被禁用账号列表。

第二次改为多 Agent 工作流。

架构分析 Agent 只读检查项目，确认请求链路为：

AdminController
    ↓
AccountService
    ↓
AccountRepository
    ↓
AuditService

它同时指出，现有单账号禁用接口已经具备权限校验和审计日志，批量功能应该复用这套逻辑，而不是另写一套权限判断。

实现 Agent 根据这份结果修改后端。它只负责接口参数、业务校验和事务处理，不修改前端及公共配置。

测试 Agent并行阅读现有测试结构，准备了以下测试项：

1. 无管理员权限时返回拒绝结果；
2. 账号列表为空时拒绝请求；
3. 超过单次批量上限时拒绝请求；
4. 部分账号不存在时事务整体回滚；
5. 操作成功后生成完整审计记录；
6. 重复提交时保持结果可解释。

实现完成后，两个审查 Agent 开始工作。

安全审查 Agent 发现接口虽然检查了管理员权限，但没有限制请求体大小。攻击者可能提交超大账号列表，导致数据库参数过多、事务持锁时间延长。

测试审查 Agent 则发现“部分账号不存在时整体回滚”只验证了接口状态码，没有重新查询数据库确认数据确实未改变。

主 Agent 汇总后追加了批量数量上限，并补充数据库状态断言。随后运行目标模块测试，再执行完整测试和静态检查。

正常的验收证据至少应该包括：

git status --short
git diff --stat
git diff --check

这些属于只读检查，不会修改代码。重点确认修改文件是否超出约定范围、是否存在意外生成文件，以及差异中是否有空白符错误。

接着运行项目自己的格式检查、类型检查和测试命令。具体命令应以项目文档和现有脚本为准，不要在不了解项目的情况下编造。

如果测试失败，主 Agent 应把失败用例重新交给负责该模块的 Agent 分析，而不是让所有 Agent 同时修改。验证完成前，也不应自动提交、推送或部署。

最终，这个案例真正提高可靠性的不是“同时运行了几个 Agent”，而是每个结论都有对应证据，每个 Agent 都有清楚的文件边界，主 Agent 还保留了最后验收权。

自定义 Agent，别只给它起个专家名字

Codex 支持配置自定义 Agent，为不同角色设置说明、模型、推理强度和沙箱权限。

项目级 Agent 可以放在项目的 .codex/agents/ 目录。下面是一个偏只读的代码审查角色示例：

name = "code_reviewer"
description = "检查代码正确性、安全风险、回归风险和测试缺口。"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
只做审查，不修改文件。
优先报告能够被代码、测试或日志证明的问题。
每个问题必须说明影响、证据位置和建议修复方式。
不要把个人风格偏好描述成缺陷。
如果没有发现明确问题，直接说明没有发现。
"""

只写“你是一名资深专家”远不够。可靠的 Agent 配置至少应该说明四件事：

它负责什么；
它不能做什么；
它应该返回什么；
什么情况算任务完成。

并发数量也可以在配置中调整。例如官方文档提供了类似下面的项目配置：

[agents]
max_concurrent_threads_per_session = 6

这个值表示会话允许的并发线程数量。它不是所有 Codex 环境都固定为 6，更不是越大越好。

实际可用数量还可能受到客户端版本、账户、组织策略和运行环境影响。Agent 越多，token 消耗、工具竞争和结果汇总成本越高。修改配置前应先查看当前版本的官方 OpenAI 文档，不要照抄过时参数。

除了手动要求“启动两个子 Agent”，还可以通过项目指令或 Skill 规定某类任务的默认分工。例如要求代码审查时始终分别检查安全、测试和可维护性。

但自动分工不能替代主 Agent 判断。一个只有几十行改动的小修复，启动五个 Agent 往往比直接完成更慢。

这些坑，准备使用前务必确认

• 不要把存在依赖关系的任务强行并行，因为下游 Agent 缺少上游结果，只能猜测或反复返工。
• 禁止让多个 Agent 无边界地修改同一个文件，因为后写入的内容可能覆盖前面的改动，也可能产生难以发现的逻辑冲突。
• 务必让只读分析先于大范围修改，因为先确认入口、调用链和测试范围，可以显著减少错误文件被修改的概率。
• 不要把子 Agent 的结论直接当作事实，因为它仍然可能误读代码；关键判断必须由差异、测试、日志或配置提供证据。
• 务必规定每个 Agent 的输出格式，因为只有“帮我检查一下”很容易得到空泛建议，无法被主 Agent 汇总和验收。
• 千万别把“没有测试失败”当成“功能正确”，因为现有测试可能没有覆盖新增边界，审稿或审查 Agent 必须主动寻找缺口。
• 务必限制权限，让探索和审查 Agent 使用只读模式，因为它们的职责是发现问题，不应该顺手修改生产配置或业务代码。
• 禁止默认授权提交、推送、部署、删除和重置，因为这些动作会改变外部状态或造成数据丢失，必须由用户明确授权。
• 务必设置并发上限和清晰的结束条件，因为每个子 Agent 都会单独消耗 token，模糊任务可能持续讨论却没有新增证据。
• 不要把当前会话看到的 Agent 数量当成 Codex 的统一产品上限，因为不同客户端、配置和组织策略可能不同。
• 务必由主 Agent 做最终整合和验证，因为子 Agent 只对自己的局部任务负责，没有任何一个局部结论能够自动代表整体合格。

Codex 多 Agent 最适合的不是把一件小事拆成十份，而是处理边界清楚、可以独立验证、需要不同视角的大任务。

可以并行的就并行：代码探索、日志分析、测试执行、安全审查和文档审校。

存在依赖的就排队：需求确认之后再设计，接口稳定之后再补集成测试，初稿完成之后再审稿，修改完成之后再做最终验证。

如果你准备第一次尝试，可以从一个低风险任务开始：

请使用两个只读子 Agent 审查当前改动。
一个检查测试缺口，一个检查安全和兼容性风险。
不要修改文件。
等待两者完成后，由主 Agent 合并重复问题，
只保留有代码证据的结论，并给出验证命令。

先把“两个 Agent 能否独立返回有证据的结果”跑通，再逐步扩展到多人实现和复杂编排。

一个人埋头干到死，解决的只是眼前任务；会拆任务、定边界、看证据、做验收，才是真正会带团队。

人是这样，Codex 也是这样。

如果这篇文章对你有帮助，欢迎点赞、在看并转发给正在使用 Codex 的同事。后续我还会继续分享自定义 Agent、项目级指令和多 Agent 代码审查的生产实践。

公众号：耕云躬行录

个人博客：躬行笔记