Codex 的 Multi-Agent，不是“同时叫来更多模型”，而是把主 thread 从亲自包办一切，升级为会拆任务、会调度、会验收的技术负责人。

当一个任务同时包含代码扫描、资料调查、测试执行、风险审查和功能实现时，单个 Agent 最大的问题往往不是能力不足，而是上下文被大量中间过程淹没：它读了几百个搜索结果、吞下大段日志，还要记住最初的目标，最后很容易顾此失彼。

Multi-Agent 的价值，是让不同 subagent 在各自的小上下文里完成明确任务，只把结论交回主 thread。主 thread 保留问题全貌、关键约束和决策权。结果不是简单地“多开几个窗口”，而是把复杂工程变成一条可控的协作流水线。

01  —

先别急着并行：默认仍然是单 Agent

多 Agent 不是默认答案。改一处文案、修一个定位清楚的 Bug、调整一个样式变量，让一个 Agent 从头做到尾，通常更快。强行拆分只会增加任务描述、结果汇总和冲突处理的成本。

一个实用的启用条件：任务中出现两个及以上可以独立完成的调查、测试、审查或实现子任务，再考虑 Multi-Agent。

适合拆分的任务，通常满足至少一项：

搜索范围大：需要扫描多个目录、追踪多条调用链或查阅多份资料。

验证维度多：单元测试、端到端测试、性能、安全、界面审查可以分别进行。

输出彼此独立：每个子任务都能给出一份完整结论，不依赖另一个任务的中间状态。

中间产物很重：日志、搜索结果和测试输出很长，但主 thread 只需要结论与证据。

02  —

主 Thread 不要下场搬砖，要掌握四件事

01	理解目标 先明确交付物、约束、风险和验收标准。目标不清，拆得越细，偏得越远。

02	切分边界 每个 subagent 都要拿到一个可独立回答的问题，并知道哪些文件能读、哪些文件能改。

03	汇总结论 要求返回结论、关键证据、风险和建议，不把几百行原始输出重新塞回主 thread。

04	最终决策 subagent 可以建议，但取舍、整合、修改范围和最终验收仍由主 thread 负责。

这也是 Multi-Agent 与“多轮对话”的关键差别：主 thread 不是消息中转站，而是整个任务的技术负责人。

03  —

模型不必一刀切：够用即可

如果当前运行环境允许为 subagent 单独选择模型，就不要让所有任务机械继承主 thread 配置。明确、重复的工作用轻量模型；常规工程任务用默认工程模型；只有高不确定性、高风险和复杂推理，才升级到更强模型。

Luna	机械、重复、高吞吐 文件清单、模式搜索、日志初筛、格式检查、批量归类。

Terra

默认工程主力 大多数分析、开发、Bug 修复、测试诊断和局部重构。

Sol	复杂与高风险升级 架构取舍、复杂正确性验证、高风险改动，或默认模型无法可靠解决的问题。

注意： 模型名称和是否允许为 subagent 单独选型，取决于你的 Codex 运行环境。没有这些型号或选择能力时，直接使用可用默认配置，保留任务拆分与升级原则即可。

模型升级可以记成 Luna → Terra → Sol。关键不是“任务看起来很大”就上最强模型，而是当前任务是否真的需要更强判断力。文件多、步骤多、描述长，都不等于推理难。

04  —

推理强度也要分级

模型决定能力上限，推理强度决定它为当前问题投入多少分析。两者都按“够用即可”配置，成本和响应速度会更可控。

low路径明确：执行测试、查找固定模式、做机械核对。

medium常规分析：判断影响范围、定位原因、设计局部方案。

high复杂判断：边界条件、数学正确性、架构与高风险决策。

常见默认组合可以是：主 thread 用 Terra + medium；机械扫描交给轻量模型和 low；真正棘手的架构或正确性问题，再升级到 Sol 和 high。它们是起点，不是死规则。

05  —

真正适合并行的是“读”，不是“写”

Multi-Agent 最常见的翻车方式，是多个 Agent 同时修改相同文件。即使每个人的局部方案都正确，最后也可能互相覆盖、重复实现，或让接口约定前后不一致。

优先并行	调查、搜索、代码扫描、日志分析、测试、独立审查
谨慎并行	不同目录、边界清晰、接口已经锁定的实现任务
避免并行	同一文件、共享状态、同一数据结构或相互依赖的重构

存在写入冲突时，最稳妥的做法是让多个 subagent 先并行调查和提出方案，再由主 thread 指定唯一 Worker 完成实现。若确实要并行开发，则必须先隔离文件范围、分支或工作区，并锁定接口。

06  —

一个真实的拆分方式

假设你要给一个已有 Web 应用增加登录限流，并确认改动不会破坏现有流程。主 thread 可以这样调度：

Agent A

只读调查： 定位登录入口、认证链路、错误处理和相关测试，返回文件与风险点。

Agent B

只读审查： 检查现有安全边界、代理头、IP 识别和敏感日志风险。

Agent C

验证设计： 列出必须覆盖的正常、失败、重试、并发和回退测试场景。

主 thread

整合与实现： 综合三份结论确定方案，交给唯一 Worker 修改，再让独立 Agent 复核 diff 和测试结果。

三个调查可以同时进行，因为它们都不改代码；实现只有一个入口，所以不会发生写入冲突；最终审查使用独立上下文，也减少“自己证明自己正确”的偏差。

07  —

把规则写进 AGENTS.md

如果希望 Codex 在复杂任务中稳定采用这套协作方式，最省心的方法不是每次重复解释，而是把规则写进通用或项目级 AGENTS.md。下面这份精简模板可以直接作为起点：

## Multi-Agent 默认使用单 Agent，主 thread 负责理解任务、拆分调度、汇总结论和最终决策。 当任务包含两个及以上可独立执行的调查、测试、审查或实现子任务时，使用 subagents。大量搜索、代码扫描、日志分析和测试输出优先下放，主 thread 只保留必要上下文、结论和决策。 为每个 subagent 按任务难度选择可用的模型与推理强度，遵循“够用即可”和逐级升级原则，不因文件多、步骤多或描述长而自动升级。 优先并行只读调查、测试和审查。避免多个 Agent 同时修改相同代码；有写入冲突风险时，由主 thrad 指定唯一 Worker，或先隔离修改范围。 Subagents 应自主完成任务，并返回简洁结论、关键证据、风险和建议。

还可以在具体任务的第一句话补上：“先判断是否存在两个以上可独立子任务；如果适合，请先给出分工，再并行调查。” 这会促使主 thread 先设计协作结构，而不是拿到需求就直接开始改代码。

最后  —

Multi-Agent 的目标不是热闹，而是清晰

衡量 Multi-Agent 是否有效，不看同时运行了多少个 Agent，而看三件事：主 thread 的上下文是否更干净，子任务边界是否足够清楚，最终结果是否更容易验证。

最小实践：默认单 Agent；出现两个以上独立子任务再拆；读任务优先并行；写任务先划边界；模型与推理强度逐级升级；最后由主 thread 统一决策和验收。