1. 单 Agent 的瓶颈为什么 Codex 一个人扛不住复杂工程很多人第一次用 Codex CLI 的时候都会经历一个蜜月期——在终端里敲一句自然语言它就能帮你生成函数、补全测试、解释报错感觉像是雇了一个随叫随到的编程助手。但只要项目稍微上一点规模比如一个前后端分离、带数据库迁移、还要跑 CI 的中型仓库你就会发现单 Agent 模式开始力不从心。这不是 Codex 本身不行而是一个 Agent 包打天下这个用法本身就违背了软件工程的常识。1.1 上下文窗口不是无限背包Codex 这类基于大模型的编码 Agent本质上是在一个有限的上下文窗口里做推理。你把整个仓库的关键文件、依赖清单、构建脚本、测试用例全塞进去窗口很快就被占满。一旦超出模型要么开始遗忘前面的约束要么对后面的代码理解出现偏差。我实测过一个大概 3 万行的 TypeScript 项目如果让单个 Agent 同时处理重构数据层 更新 API 契约 补集成测试它在第三步时经常会把第一步定下的接口命名规则忘掉生成出前后不一致的代码。这就像让一个人同时记住三份不同的需求文档还要交叉引用人脑都会乱何况是模型。多 Agent 协同的第一个价值就是把记忆负担拆开——每个 Agent 只负责自己那一块上下文通过明确的接口约定来交换信息而不是把所有东西都堆在一个窗口里。1.2 角色混淆导致的精神分裂单 Agent 最隐蔽的坑是角色混淆。你让它既当架构师又当实现者还当测试员它在生成代码时会不自觉地在这几个视角之间跳来跳去。表现就是写业务逻辑的时候突然开始写测试断言写测试的时候又去改业务实现最后交付的东西边界模糊。我在一个真实项目里见过 Codex 单 Agent 模式下它把本该放在测试文件里的 mock 数据直接写进了生产代码理由是这样测试更方便——这就是角色没有隔离的典型后果。多 Agent 协同的核心思路是给每个 Agent 一个单一且明确的职责一个专门做需求拆解和接口设计一个专门写实现一个专门做审查和测试。它们之间通过结构化的产物比如接口定义文件、任务清单通信而不是靠一个 Agent 的临场发挥。1.3 并发与串行的取舍还有一个现实问题单 Agent 是串行工作的。它改完 A 文件才能改 B 文件跑完 lint 才能跑测试。对于可以并行的工作比如同时给三个独立模块补单元测试单 Agent 只能一个个来效率上不去。多 Agent 架构允许你把互不依赖的任务分发给不同的 Agent 实例并行处理最后再合并结果。当然并行也带来了冲突合并的新问题这个后面会专门讲怎么处理。提示不要一上来就追求全自动多 Agent 流水线。我建议先从两个 Agent 分工开始比如一个负责规划、一个负责执行跑顺了再往上加角色。一次性搭五个 Agent 互相调用调试成本会让你怀疑人生。2. 多 Agent 协同的三种落地形态聊完为什么得说清楚多 Agent到底长什么样。市面上的说法很杂有人指的是多个模型实例互相调用有人指的是一个主控 Agent 调度一堆子任务。我按实际工程里能落地的形态分成三类你可以根据自己的场景选。2.1 主从式一个 Orchestrator 带若干 Worker这是最容易理解和实现的一种。你有一个主控 AgentOrchestrator它负责接收人类的需求、拆解任务、分发给下面的工作 AgentWorker最后汇总结果。Worker 之间不直接通信所有协调都经过主控。这种结构的好处是控制流清晰出问题容易定位——是拆解错了还是某个 Worker 执行错了一目了然。缺点是主控容易成为瓶颈而且主控的上下文压力依然不小因为它要记住所有子任务的进展。在 Codex CLI 的语境下你可以把主控做成一个脚本用命令行依次调用 Codex 处理不同任务把上一步的输出作为下一步的输入。虽然土但非常稳。2.2 流水线式按阶段接力流水线式是把整个开发流程切成固定阶段每个阶段一个 Agent产物像流水线一样往下传。典型的分段是需求分析 → 接口设计 → 代码实现 → 测试生成 → 代码审查。每个 Agent 只关心上游给我的输入和我要产出的输出职责极其清晰。这种模式特别适合有固定交付规范的团队比如你们公司要求每个功能必须带单测和变更说明那流水线就能把这些规范固化进每个阶段的 Agent 提示词里。形态适用场景优点主要风险主从式任务边界清晰、需要动态拆解控制流清晰、易调试主控成瓶颈流水线式流程固定、规范严格职责清晰、产物可追溯灵活性差对等式需要多视角辩论、方案评审能暴露盲点协调成本高、易发散2.3 对等式多 Agent 互相评审对等式是让几个平级的 Agent 就同一个问题各自给出方案然后互相评审、辩论最后收敛出一个结论。这种模式在方案选型架构评审这类需要多视角的场景里特别有用。比如让一个 Agent 主张用关系型数据库另一个主张用文档型第三个专门挑两者的毛病最后主控综合。它的价值在于对抗性——单个 Agent 容易陷入自己的思维定式多个 Agent 互相挑刺能逼出更全面的考虑。但代价是 token 消耗成倍增加而且如果没有收敛机制几个 Agent 可能无限辩论下去。我的经验是给辩论设一个硬性轮次上限比如三轮到点必须出结论。3. 用 Codex CLI 搭一套最小可用的多 Agent 工作流理论说再多不如跑一遍。这一节我带你用 Codex CLI 搭一套最小可用的双 Agent 工作流一个规划 Agent负责把需求拆成任务清单一个执行 Agent负责按清单逐条实现。这套东西不需要任何额外框架纯靠命令行和文件交换就能跑起来。3.1 环境准备与 Codex CLI 安装的常见坑先把 Codex CLI 装好。官方推荐的方式是全局安装npm install -g openai/codexlatest这一步在 Windows 上特别容易翻车。我见过最多的报错是npm:无法加载文件 ... 因为在此系统上禁止运行脚本这是 PowerShell 的执行策略问题不是 Codex 的问题。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned然后重新开一个终端再装。另一个高频报错是unable to locate the codex cli binary or required runtime components这通常意味着 Node 版本太低或者全局 bin 目录没进 PATH。先确认node -v在 18 以上再检查npm config get prefix输出的路径有没有加到环境变量里。装完之后跑codex --version验证。如果提示需要登录按引导完成账号授权即可。这一步网络环境要稳定否则会出现welcome to codex之后卡住不动的情况。注意安装过程中如果遇到网络相关的报错优先检查本地网络和代理配置是否正常不要盲目重装。很多装不上其实是网络抖动导致的下载中断。3.2 规划 Agent把一句话需求变成结构化任务清单规划 Agent 的职责很单一读人类给的需求输出一份结构化的任务清单。关键是输出格式要固定因为下游的执行 Agent 要解析它。我一般让它输出 JSON 或者带固定标记的 Markdown。给规划 Agent 的提示词大概长这样你是一个任务规划助手。用户会给你一段功能需求。 请把它拆解成若干可独立执行的子任务每个子任务包含 - id唯一编号 - title一句话描述 - files预计涉及的文件路径 - depends_on依赖的其他任务 id 列表 - acceptance验收标准 只输出 JSON 数组不要输出任何解释文字。为什么要强制 JSON因为执行 Agent 要按depends_on决定执行顺序靠自然语言描述这个任务要在那个任务之后做是没法可靠解析的。结构化输出是多 Agent 协同的地基。我实测下来规划 Agent 最容易犯的错是拆得太粗。比如实现用户登录这种任务它可能就输出一条结果执行 Agent 拿到之后还是不知道从哪下手。解决办法是在提示词里明确要求每个子任务的工作量控制在单个文件、单次提交以内逼它拆细。3.3 执行 Agent按清单逐条落地并回写状态执行 Agent 拿到任务清单后逐条处理。每处理完一条就把状态从pending改成done并附上实际改动的文件列表。这样即使中途中断下次也能从断点继续。执行 Agent 的提示词要点你会收到一个任务对象和当前仓库状态。 请只完成这一个任务不要越界修改其他文件。 完成后输出 - status: done 或 blocked - changed_files: 实际修改的文件列表 - note: 如果 blocked说明原因这里有个关键设计执行 Agent 一次只做一个任务。不要让它一口气把清单全做完那样又回到了单 Agent 的老路上下文会爆。一次一个任务做完就退出由外层脚本负责循环调用。这样每个任务的上下文都是干净的。3.4 用脚本把两个 Agent 串起来外层用一个简单的 shell 或 Python 脚本做调度import json, subprocess def run_codex(prompt): result subprocess.run( [codex, exec, prompt], capture_outputTrue, textTrue ) return result.stdout # 第一步规划 plan_raw run_codex(open(plan_prompt.txt).read() \n\n需求 requirement) tasks json.loads(plan_raw) # 第二步按依赖顺序执行 done set() while len(done) len(tasks): for t in tasks: if t[id] in done: continue if all(d in done for d in t[depends_on]): result run_codex(build_exec_prompt(t)) print(f任务 {t[id]} 完成{result}) done.add(t[id])这段代码很朴素但它体现了多 Agent 协同的精髓Agent 之间不直接对话通过文件和结构化数据交换信息。规划 Agent 的输出是执行 Agent 的输入执行 Agent 的输出是调度脚本判断下一步的依据。4. 协同过程中最容易翻车的四个地方多 Agent 跑起来之后真正的挑战才刚开始。下面这四个坑是我在实际项目里反复踩过、也见过别人踩的提前知道能省很多时间。4.1 接口漂移上游改了约定下游还在用旧的规划 Agent 定下的接口命名执行 Agent 可能因为觉得这样更好而擅自改动。等下一个 Agent 接手时发现对不上。这就是接口漂移。根因是 Agent 之间缺乏强约束的契约。解决办法是把接口定义单独抽成一个文件比如contract.json所有 Agent 在动手前必须先读这个文件且不允许修改它。如果确实需要改必须回到规划阶段重新生成契约而不是在执行阶段偷偷改。我在一个项目里吃过这个亏规划 Agent 说用户 ID 字段叫user_id执行 Agent 写成了userId测试 Agent 又按user_id去断言结果测试全红排查了半天才发现是命名不一致。从那以后我强制所有 Agent 共享一份契约文件。4.2 上下文污染Agent 读到了不该读的东西执行 Agent 在处理任务 A 时如果顺手把任务 B 相关的文件也读进了上下文就可能被带偏。比如它在实现登录逻辑时读到了支付模块的代码然后灵机一动把支付相关的工具函数也改了。防范手段是限制每个 Agent 的文件访问范围。在提示词里明确告诉它你只能修改 files 列表里列出的文件并且在调度脚本层面做校验——如果执行 Agent 报告改动的文件超出了预期范围就标记为异常人工介入。4.3 死循环两个 Agent 互相甩锅对等式或带反馈的流水线里很容易出现A 说 B 的产出不合格B 说 A 的要求不明确这种死循环。我见过一个案例审查 Agent 一直拒绝实现 Agent 的代码理由是缺少错误处理而实现 Agent 每次都加了一点错误处理但审查 Agent 总能找到新的问题来回十几轮。解决办法是给每个环节设硬性轮次上限和升级机制。比如审查最多两轮两轮还不过就升级给人类决策而不是让两个 Agent 无限扯皮。同时审查 Agent 的反馈必须是可执行的——不能只说错误处理不够要说第 42 行的 fetch 调用没有 catch请补上。4.4 并发写冲突两个 Agent 同时改一个文件如果你开了并行执行两个 Agent 同时改同一个文件后写的会覆盖先写的。这个在 Git 层面表现为冲突但在 Agent 层面可能悄无声息地丢改动。规避方法是在任务规划阶段就保证文件级互斥——同一个文件在同一批次里只能被一个任务涉及。规划 Agent 的提示词里要加一条如果两个任务涉及同一文件请合并为一个任务或标注依赖关系。这样从源头避免了并发写同一文件。翻车点根因应对手段接口漂移缺乏强约束契约共享 contract 文件禁止执行阶段修改上下文污染文件访问范围失控限定可改文件脚本层校验死循环无轮次上限设硬性轮次超限升级人工并发写冲突任务粒度重叠规划阶段保证文件级互斥5. 让协同真正提效的几个进阶技巧把基础流程跑通之后下面这些技巧能让你的多 Agent 工作流从能用变成好用。5.1 给每个 Agent 配一份岗位说明书不要每次调用都临时拼提示词。把每个角色的系统提示词固化成一个文件比如roles/planner.md、roles/executor.md、roles/reviewer.md。调用时直接读文件拼接。这样做的好处是角色定义可版本管理改一次全局生效也方便团队成员共享同一套规范。岗位说明书里要写清楚三件事职责边界你负责什么、不负责什么、输入输出格式收到什么、产出什么、禁止事项绝对不能做什么。第三点最容易被忽略但恰恰最重要。比如执行 Agent 的禁止事项里必须有一条不得修改 contract 文件。5.2 用检查点代替全自动很多人追求端到端全自动需求进去、代码出来。但实际项目里全自动的返工成本往往比半自动高。我的做法是在关键节点设检查点规划完成后暂停人工扫一眼任务清单合不合理执行完成后暂停人工看一眼改动范围对不对。确认无误再继续。检查点不丢人反而省时间。一个规划错误如果放任执行 Agent 跑下去可能改了几十个文件才发现方向错了回滚成本极高。花两分钟看一眼清单能省两小时返工。5.3 把测试 Agent 当成独立第三方测试 Agent 千万不要复用执行 Agent 的上下文。它应该只拿到需求描述和最终代码然后独立地写测试。如果它知道执行 Agent 是怎么想的就会不自觉地配合实现写出那种永远通过的假测试。我一般让测试 Agent 先根据需求写测试用例再拿代码去跑。如果测试挂了说明实现有问题如果测试全过但我觉得覆盖不够就让它补充边界用例。这种先写测试再看实现的顺序能有效暴露实现里的漏洞。5.4 记录每个 Agent 的决策日志多 Agent 系统出问题时最难的是定位是哪个环节出的错。解决办法是让每个 Agent 在产出结果的同时附上一段简短的决策说明我为什么这么拆、为什么这么改、为什么拒绝。这些日志汇总起来就是一条完整的决策链。日志不用长一两句话即可。但有了它回溯问题时你能快速判断是规划阶段的锅还是执行阶段的锅。我在一个项目里就是靠决策日志发现某个 bug 的根源是规划 Agent 把两个有依赖关系的任务标成了独立任务导致执行顺序错了。6. 关于多 Agent 协同我踩过之后的几点实在话多 Agent 协同不是银弹它解决的是单 Agent 上下文有限、角色混淆的问题但引入了协调成本、接口一致性、调试复杂度的新问题。用不用取决于你的项目复杂度。如果只是改个 bug、写个小脚本单 Agent 完全够用硬上多 Agent 是自找麻烦。真正值得上多 Agent 的场景是那种任务可以清晰切分、且切分后各块相对独立的工程。比如给一个已有项目补全测试、做一次跨模块的重构、按规范批量生成 CRUD 代码。这些场景里多 Agent 的分工优势能实实在在体现出来。最后分享一个我自己的判断标准如果你能用一句话把某个 Agent 的职责说清楚那它就值得独立成一个 Agent如果说不清楚说明这个职责还没想明白先别拆。我见过太多人为了多 Agent而多 Agent拆出一堆职责重叠的角色最后协调成本比单 Agent 还高。工具是为人服务的别被概念牵着走。