前阵子有一个迁移任务我本来打算让 Codex 一个人从头扛到尾。项目是一个老仓库跨了几个模块还牵扯到数据格式兼容。前一半干得挺利索到了中后段就开始不对劲它开始重复改同一个文件把前面确定好的方案推翻了一半甚至把两个模块的接口改得对不上。我盯着对话记录发现问题不在代码生成而在上下文它把自己早期的结论渐渐“忘”了或者说是被后续讨论冲刷掉了。那次之后我再也没有把一个完整大型任务单独交给 Codex 过。解决办法是把它放进一个多 Agent 流程里让不同角色各管一段Codex 只干它最擅长的那部分。这篇文章就是那次实战的完整复盘讲讲为什么要拆、怎么拆、以及拆完之后遇到的坑。1. 为什么单个 Agent 会在系统性任务上卡住1.1 瓶颈不是 Token 长度而是上下文职责半径很多人的第一反应是“上下文太短”但实际上当前模型几十万 Token 的窗口并不小。真正的问题是单 Agent 在长时间任务里要同时承担太多职责它需要记住最初目标需要维护已经做过的所有决策需要理解最新的文件内容还需要判断下一步动作。这些信息挤在一起模型不会优先保证“最初目标”它会优先响应最近几轮对话里的信息。我在那次重构里观察到一个典型场景第三轮时 Codex 定义了一个统一的 DTO 结构第七轮它又在某个模块里生成了一套几乎重复的类型定义。不是它偷懒是早期定义已经被大量中间内容冲淡了。单 Agent 的上下文就像一张白板写满了前面的内容你让拿着这块白板的人继续做全局设计他只能基于最上面几行字来做判断。这就是我一直强调的“责任半径”概念。一个 Agent 能处理的任务大小取决于它需要同时维护多少决策变量而不是窗口有多大。把需求列表、方案取舍、代码实现、测试反馈全塞给一个 Agent它相当于同时扮演产品经理、架构师、开发者和测试员那上下文里必然互相污染。1.2 设计和实现混在一个上下文里是混乱的起点单 Agent 更隐蔽的问题是设计和实现被放在同一个推理过程里。当你对 Codex 说“帮我重构 A 模块顺便把 B 模块的调用改掉”它会在生成代码的过程中自己做出设计决策。这些决策没有经过显式的讨论也没有被记录成文档它就是凭当前上下文“顺手”定了。小任务无所谓大任务就会有连锁反应。A 模块设计错了B 模块基于错误设计继续写等发现的时候两个模块的改动已经纠缠在一起。回滚哪个都不干净最好的办法是让设计决策从实现过程中剥离出来由一个 Agent 专门产出方案另一个 Agent 专门落实方案。我有一次故意做了对比实验同一个任务一半用单 Agent 直接执行一半拆成“设计 Agent 实现 Agent”两步做。单 Agent 版本的第一次输出看起来更快但后续修修补补迭代了四轮拆成两步的版本设计阶段多花了几分钟实现阶段一次通过总耗时反而更短。多 Agent 不是说让多个模型并行跑而是让一个复杂过程被拆成多个职责单一的阶段。2. 多 Agent 协同的核心心智模型2.1 三种常用的编排拓扑搞多 Agent 之前先说清楚编排结构。我实际尝试过三种各有适用场景。第一种是流水线式就是 A 的输出直接成为 B 的输入像工厂流水线一样。适合任务步骤之间有明确顺序的场景比如先做数据分析、再做方案设计、最后写代码。好处是上下文传递很干净坏处是一旦中间某一步失败整条线都得重新跑。第二种是主管/下属式一个 Supervisor Agent 负责任务拆分和结果验收下面挂几个 Worker Agent 分别执行。这是编码任务里最常用的一种结构。主管不写业务代码它只负责维护任务列表、派发工作、检查产出是否达标。工人之间不直接通信所有交互都通过主管中转上下文隔离做得很好。第三种是黑板式所有 Agent 读写同一块共享状态比如同一个文件、同一个数据库记录。这种方式很适合协同调试多个 Agent 各看各的错误但要做好并发控制否则互相覆盖。我自己在编排编码任务时最常用的是主管/下属式。原因很现实编码任务里最贵的不是生成代码而是保证上下文一致性。主管维护全局目标工人只看到被派发的那一小块任务就不会出现“各改各的最后接不上”的问题。2.2 角色不是“更聪明”而是“更窄”很多人误解多 Agent 的价值以为多个 Agent 并行能更快出结果。实际上把任务拆给多个 Agent如果每个 Agent 的角色定义得不够窄协同效率反而比单 Agent 更低。多个模糊的 Agent 只是把“一个模糊的上下文”复制成了好几份。真正的要点是用上下文隔离换取行为稳定。每个 Agent 不需要知道全局它只需要知道自己负责的那一小块。我通常会定义三类角色规划 Agent负责分析需求拆解任务清单明确验收标准。它不写代码只产出方案文档和任务列表。执行 Agent负责按任务清单逐个实现。它不讨论方案只按规划 Agent 给出的规格写代码。审查 Agent负责检查执行结果跑测试、看 diff、指出问题。它不直接改代码只把问题列表返回给执行 Agent。这三个角色如果让同一个 Agent 干权限就互相污染了。写代码的时候顺手改了方案审查的时候又不好意思挑自己毛病。分开以后每个 Agent 的上下文里只需要装自己角色的规则和当前任务输出质量会明显稳定下来。3. 把 Codex 放进多 Agent 团队的正确姿势3.1 Codex 最适合扮演“执行工人”而非“总指挥”很多人把 Codex 当成一个万能入口什么任务都从一个对话框发起。在多 Agent 协同里我建议反过来把 Codex 当作一个可编程调用的执行单元通过命令行工具调用它让它完成被明确指派的任务而不是给它一个超大目标让它自由发挥。Codex CLI 本身支持非交互模式这意味着你可以把它嵌进脚本由外部编排器分配任务。它在多 Agent 团队里的定位应该是写代码的那个角色。你给它一份干净的任务描述它返回一份代码改动仅此而已。我实际用下来最顺手的调用方式是这样的codex exec --full-autonomy \ -C /path/to/project \ 实现 user_service 模块中的 get_user_profile 方法要求基于 schema.sql 中定义的 users 表结构返回完整资料对象不需要写测试。注意任务描述里包含了三样东西明确的操作对象、明确的参考文件、明确的验收边界。这比说“帮我实现用户服务”要好用得多因为后者把设计决策又抛给了 Codex。任务描述越窄Codex 的行为越可预测外部编排器就越容易判断它有没有完成任务。3.2 上下文由编排器统一管理而不是靠 Codex 自己记单 Agent 工作流里Codex 会尝试记住整个对话历史。多 Agent 工作流里这段历史应该由外部编排器来记每次调用 Codex 都是一个新的会话只携带本次任务需要的上下文。用一个具体的例子说明。假设有一个全栈功能涉及前端页面、后端接口、数据库迁移三块工作。如果让 Codex 一口气做完它可能在后端接口里设计了某个字段但前端页面还在用旧字段名最后花了很长时间才发现两边不一致。在多 Agent 流程里我会先让规划 Agent 产出一份接口文档把字段名、类型、边界都定义清楚。然后执行阶段前端任务调一次 Codex后端任务再调一次 Codex但每次都把同一份接口文档塞进任务描述。Codex 不需要记得前端改了什么它只需要按文档实现后端这个字段名就不会错。从实际操作上讲编排器要维护一份可识别的“当前工作版本”。不管哪个 Agent 做了改动最终都要以文件系统里的代码为准。Agent 与 Agent 之间千万别直接传自然语言描述传文件路径、传结构化文档、传 commit 记录都比传一段描述可靠。4. 多 Agent 协同编排的工程细节4.1 编写 Agent 职责提示词的模板既然要让多个 Agent 各司其职职责提示词就是整个系统的地基。我总结了一套模板用下来效果不错你是一个 [角色名称]。 你的职责是 [具体职责描述]。 你不需要 [明确不做的事情]。 你有以下输入 [列出输入文件、输入数据结构] 你必须输出 [列出输出格式、输出文件路径、验收标准] 约束条件 [列出版本要求、代码风格、禁止事项]看起来很简单但每一步都有讲究。“你不需要做什么”这一条特别值得强调。比如执行 Agent 不需要讨论方案那么我就在约束里写“收到任务后直接实现代码不要输出方案分析”。一旦模型开始输出方案分析上下文就开始膨胀了没过几轮又会忘记最初的任务目标。职责提示词要放在每次调用的 system prompt 或者任务描述开头而不是放在一个全局配置里设置一次。因为 Agent 服务端通常不会保存跨会话的角色记忆你每次调用都得显式声明这个 Agent 的角色。重复写这些规则虽然看起来笨拙但它是保证多次调用行为一致的唯一办法。4.2 任务交接用文件系统当通信总线多 Agent 协同最大的坑是 Agent 之间直接传长文本。A 的输出是一段描述B 拿这段描述当输入描述经过两次传播就失真了。我现在的做法是让 Agent 之间的交互以文件系统为中介。具体做法是建一个工作目录规划 Agent 的输出写入tasks/task-001.md执行 Agent 的产出写入outputs/task-001.patch审查 Agent 的结论写入reviews/task-001.review。不管哪个 Agent 需要信息都去对应目录下读文件而不是从前一个 Agent 的输出文本里粘。文件命名也要讲究。不要用final.md、report.md这种没有版本概念的名字要用带编号或带 commit 的命名。因为审查 Agent 是有可能打回任务的执行 Agent 改完之后文件要能区分是第几版。我通常把执行 Agent 的每次修改都提交为一次本地 git commit审查 Agent 读取的是 commit 列表和最新 diff打回时指定 commit 号这样整个流程都可以回退。4.3 编排器本身也要有提示词很多人搭了多 Agent 结构却忘了编排器本身也是需要提示词的。我在早期犯过这个错规划 Agent、执行 Agent、审查 Agent 的提示词写得挺好但安排它们干活的那个“主管循环”完全没有提示导致任务被错误地拆解、派发顺序混乱。主管 Agent 的提示词核心是任务列表管理。它要能读取用户目标拆解成任务然后逐个派发。我会给它一个非常机械的流程提示你是任务协调器。你的工作流程 1. 读取用户提供的目标描述。 2. 将目标拆解为若干独立任务每个任务写入 tasks/ 目录。 3. 每次只派发一个任务给执行 Agent等待执行结果。 4. 将执行结果交给审查 Agent 检查。 5. 审查通过则标记完成不通过则将问题反馈给执行 Agent。 6. 全部任务完成时汇总所有任务状态。这一段的作用是让主管 Agent 的行为保持可控。虽然理论上它可以自由发挥但不给它发挥空间反而更安全。多 Agent 系统的稳定性从来不靠某个 Agent 的聪明而靠流程的确定性。5. 实战中踩到的坑和排查过程5.1 配置项报错“忽略 1 个无法识别的配置设置”实际部署多 Agent 流程时我遇到过一遍 Codex CLI 启动时输出一条提示ignoring 1 unrecognized configuration setting翻译过来就是配置里有它不认识的键。这看起来只是警告但一定要当成错误排查。大多数情况下是config.toml里手写的键名拼错了或者某个配置项在升级后改了名。这个警告意味着你认为生效的某个配置实际上没有生效。我那次就是这样配置里写了一个模型参数但键名拼错了结果 Codex 一直在用默认参数跑行为表现完全不是预期的那种。排查步骤很简单先检查~/.codex/config.tomlLinux/macOS或者%USERPROFILE%\.codex\config.tomlWindows把报错里提到的配置项单独拎出来确认拼写。对照官方文档核对一遍不要凭记忆写配置。如果确认没有问题再检查是不是本地装了多个版本的 Codex导致读到了旧版配置模板里的键。5.2 登录态和授权问题的现场处理多 Agent 流程里经常要并发调用 Codex这时最容易遇到的是auth token is unavailable或者登录态失效的问题。单 Agent 用的时候弹窗登录一次能用很久并发场景一多多个子任务同时凑齐了触发登录请求整个流程就会卡住。我的处理思路是在编排器启动前先把 Codex 的登录态验证好不要等到任务派发了再处理。跑一行命令确认登录状态确认无误后再拉起多 Agent 任务。如果任务跑了一半遇到 token 失效优先停止派发新任务把已完成的子任务做好提交记录修复登录态后分批重试绝不带着失效 token 硬试。还有一次出现过“组织设置加载失败”的提示但本地任务是能跑的。这种情况多数是在企业网络环境里CLI 访问组织配置的时候遇到了一时性的网络问题。我当时的处理是跳过组织配置同步用默认配置继续本地执行成功了。但如果是企业强制要求组织策略那就不能跳过需要先恢复网络链路再继续。5.3 长任务对话断裂与上下文丢失另一个常见坑是执行 Agent 在长任务里因为某种原因对话会话被打断了。Codex CLI 非交互模式下任务执行到一半如果网络中断或者本地进程被杀整个会话就废了之前所有推理过程全部丢失。一开始遇到这个问题我会尝试重发同样的任务然后发现结果和之前跑的不完全一样。模型的随机性决定了只要上下文有细微变化输出就不可能精确复现。后来我学到的做法是把大任务拆成小块每一块的任务描述都自带验收标准就算中途断了重跑的成本也可控。这种场景建议多利用文件系统里已有的代码状态。如果执行 Agent 在断线前已经修改了部分代码不要重新从头生成而是告诉新会话“代码已经在文件里你检查当前状态只做剩余部分”。把这个原则写进编排器提示词能省不少重试的时间。5.4 并发执行时的问题多个 Agent 互相干扰多 Agent 听起来就该是并行的但编码任务我不建议真的让多个执行 Agent 同时写同一个仓库。它们会各自读取当前代码状态各自修改最后写回时互相覆盖产生根本排查不出来的竞态问题。安全的做法是多个执行 Agent 并行写不同的模块但如果它们之间存在共享文件那就必须串行执行。判断标准很简单有没有可能两个任务修改同一个文件只要存在这种可能就把它们放进同一个队列。我做过一个折中方案允许审查 Agent 在执行 Agent 干活的过程中并行跑静态检查因为它们两个不写同一个文件。规划 Agent 也可以提前准备后续任务但它只能写任务文档不能动代码。真正写代码的执行 Agent一次只跑一个。5.5 模型选择和路由的错误最后一个值得记录的问题是编排器里配置了多个模型但某些模型根本不支持被 Codex CLI 调用。我遇到一次报错提示某个模型名称不被当前方式支持排查下来是编排配置里写错了模型标识符。这种情况去模型提供方核对一下准确模型名别在配置里手动猜。另外要注意多 Agent 流程中不同 Agent 走不同模型是常态但主管 Agent 的模型最好和工人的模型分开。主管对推理能力要求高工人的模型更追求执行速度和成本。我的经验是主管用更强的模型工人用响应更快的模型不要全部混成一个。6. 我现在的多 Agent 标准流水线把这轮实战沉淀下来之后我搭了一套固定的参考流程分享出来给大家抄作业。整条流水线按这个顺序执行需求收集阶段把用户需求写入requirements.md不做任何技术方案。规划阶段规划 Agent 读取requirements.md产出技术方案文档design.md里面必须包含模块拆分、接口定义、数据变更、验收标准。任务拆解阶段主管 Agent 基于design.md拆分任务每个任务是一个独立 markdown 文件包含任务说明、涉及文件、输出要求。执行阶段执行 Agent通常是 Codex按任务文件逐个实现。每完成一个任务自动创建一次 git 提交。审查阶段审查 Agent 读取最近一次提交的 diff运行测试和静态检查输出审查结论。反馈阶段审查不通过把问题列表交给执行 Agent 重新修改通过后任务标记完成。这套流水线的最大好处是每个 Agent 的上下文都被控制住了。规划 Agent 不关心具体代码怎么改执行 Agent 不关心整体方案怎么定审查 Agent 不关心最初需求是什么。每个环节都有明确的输入和输出代码状态始终可回退、可追踪。不要把这套东西理解成只在复杂大项目里才能用小任务也可以简化。哪怕是修一个 bug我也会让规划 Agent 先写一句话的定位再让 Codex 去改最后让审查 Agent 看一眼 diff。就是多花几十秒的事但质量稳定性比直接跟 Codex 说“帮我修一下”要强太多。根据自己的实际经验我不推荐一上来就搭一个很重的多 Agent 系统那会把自己淹没在配置和管理里。选一个你经常做的中型任务先手动拆两步走一次规划、一次执行。感受一下上下文分离带来的变化然后再逐步添加审查角色和文件通信机制。多 Agent 协同并不是什么神秘的技术它就是把你平时在团队里分配工作的逻辑搬到了模型调用层面而已。