一句话总结
Codex 远不止是一个 AI 编程助手——它是一套完整的 Agent 编排控制平面。理解它的 8 种拓扑和 3 层原语，你就能像管理工程团队一样调度 AI。
riba2534 的这篇文章为什么值得读？
7 月 30 日，开发者 riba2534 在 X 上发布了一篇万字长文《Codex 进阶指南：作为 Multi-Agent 编排控制平面》，短短几天就获得了 31 万阅读、2900+ 收藏。
这篇文章之所以爆火，是因为它第一次系统性地讲清楚了 Codex 的编排能力模型——不是”怎么用 Codex 写代码”，而是”怎么用 Codex 管一群 Agent 一起干活”。
本文是对 riba2534 原文的精华解读和实战补充。我会用更贴近日常开发的视角，帮你快速建立对 Codex Multi-Agent 编排的全局认知，并给出可以直接套用的实战建议。
先搞懂 Codex 的”三层四对象”
进编排之前，必须先把几个概念分清楚。
四个核心对象
| 对象 | 是什么 | 关键特征 |
|---|---|---|
| Task | 持久 Agent，出现在侧边栏 | 跨项目、跨主机、长期存在 |
| Subagent | Task 内部临时派生的工作者 | 短生命周期、跑完即散 |
| Project | Task 的绑定目标 | 决定 Task 在哪干活、能访问什么文件 |
| Thread | 一个会话的完整对话记录 | Task 的”记忆” |
最关键的区分：Task 和 Subagent。Task 是你”团队里的正式成员”，Subagent 是”临时叫来帮忙的”。两者的生命周期、可见性、控制方式完全不同。
三层运行面 + 一层控制面
Codex 的能力模型是四层结构：
- 持久任务层 — 跨项目跨主机的 Task，你的”团队”
- 任务内协作层 — 一个 Task 派生的 Subagent 团队，你的”工作组”
- 执行环境层 — Project / Local / Worktree / Remote SSH / Cloud，决定”在哪干”
- 可编程控制面（App Server） — 给外部程序的 API 入口，实现脚本化编排
人类站在最上面：给目标、纠偏、拍板。四层结构让 Codex 从”工具”变成了”平台”。
执行位置：决定 Agent 在哪干活
Codex 支持五种执行位置，每种都有明确的适用场景：
Local
直接在项目的日常 checkout 里干活。好处是文件变化立刻反映到 IDE 和 dev server，适合需要前台交互的任务。代价是多个并行写任务会互相干扰。
Worktree（⭐ 杀手级能力）
Codex 托管的独立 Git checkout，底层用的就是 git worktree。同一个仓库的多个 Task 可以各占一个文件树并行改动，diff、测试、产物完全独立。
这是”多方案竞赛”类拓扑的基础——三个方案各占一个 Worktree，互不干扰，最后比结果。
Remote SSH
Task 跑在已连接的 SSH 主机上。shell、文件、Git、MCP 全部来自远端机器。这是”按环境路由”的基础——编译放大机器、内网访问放内网机器、UI 验证放本地。
Cloud
ChatGPT 云端工作环境，不依赖本地 checkout。适合离线推进或云端并行。
Handoff（换地方 vs 换人）
Handoff 解决的是”在哪里执行”——把同一个 Task 从本机迁到远端，Task ID 和历史全保留。但”把任务交给另一个 Agent”属于语义层的交接，Codex 没有为它提供专门的原语，得自己用几个现成的组合出来。
八种 Agent 拓扑：什么时候用什么
这是原文最精华的部分。riba2534 总结了 Codex 原生支持的八种编排拓扑，每种都有明确的适用场景。
① Supervisor（项目经理模式）
找一个会话当项目经理，其他会话都归它管。
你只跟 Supervisor 说话，由它去建人、派活、催进度、汇总结果。适合同时推进多件独立事务的场景——比如后端接口、前端页面、文档更新三条线同时走。
你 → Supervisor → Task A（后端）
→ Task B（前端）
→ Task C（文档）
→ 汇总 → 汇报给你
实战建议：Supervisor 本身也应该是 Projectless Task——不绑具体仓库，专注于协调。
② Fan-out / Gather（分派-汇总，最常用）
同一件事切成互不相干的几块，同时开工，做完拼起来。
最典型的例子：同一个 PR，让一个 Agent 看安全风险，一个看测试缺口，一个看性能，最后由汇总角色合成一份报告。
切分原则：块与块之间不需要通信。如果 A 干到一半必须知道 B 的结论，就不该被切成并行。
实战建议：用子 Agent 承载时轻量省 token，用持久 Task 承载时留痕可追。关键差异——wait_threads 是 wait-any，不是 wait-all，等全部完成要自己写循环。
③ Pipeline（流水线）
一批东西要过同样的几道工序。关键是”谁先做完谁先往下走”。
比如 20 个文件依次做翻译→校对→排版。正确的做法不是等全部翻译完再一起校对，而是第 3 个翻译完立刻去校对，不等第 17 个。
实战建议：Pipeline = wait-any + 每个 item 独立状态 + 派下一阶段。别写成”等所有阶段完成”的同步模式。
④ Graph Workflow（依赖图）
任务之间有网状的依赖关系。这是八种里唯一绕不开写代码的。
发版前要跑的那一堆检查——有的能并行，有的必须等前面几个好了才能开始。需要一个专门的状态容器（Registry）记录”现在哪些前置条件已齐、可以开跑”。
Thread 存的是 Agent 对话，Registry 存的是业务 DAG——这两个不是同一个东西。想靠翻聊天记录还原”跑到第几步了”，迟早出问题。
⑤ Generator-Critic（生成-评审循环）
一个角色干活，另一个专门挑毛病，挑出来打回去重做。
要点全在”挑毛病的不能是干活的那个自己”。同一个会话刚写完代码紧接着自查，它会倾向于确认自己的判断。换个从头到尾没参与实现的角色去审，才审得出东西。
实战建议：更省事的做法是把判据写进 SubagentStop hook，不达标就返回 decision: "block" 让它自己再跑一轮——连主 Agent 都不用参与。
⑥ Fork + Worktree 多方案竞赛
同一个问题让几个角色各写一版，互不干扰，最后挑最好的。
重构有三种设计思路，光讨论不出结果？三种都实现出来，各自跑测试，拿 diff 和测试结果比。每个候选必须待在自己的 Worktree 里、用自己的分支。
⑦ Race（竞速模式）
派几个候选同时算，第一个交出能通过验证的答案就采纳，剩下的作废。
适合”只要有一个能跑通就行”的活——比如偶发失败的测试，三种排查思路同时试，谁先复现就按谁的走。
实战建议：用子 Agent 承载 Race（可以直接 interrupt_agent 掐掉落后的），用持久 Task 承载则没法中断（codex_app 那 13 个工具里没有线程级中断）。
⑧ Quorum（共识模式）
让几个候选各自独立算，累计到 K 个给出相同答案才采纳。
适合”答案对不对本身不好判断”的活——比如估算数据迁移的影响面，单次结果没法验证，但三个独立跑出来是同一个数，可信度就高多了。
关键在于候选之间必须真的独立。 如果都从同一份被污染的上下文出发，三个一致也说明不了什么。
拓扑选择速查表
| 场景 | 推荐拓扑 | 承载方式 |
|---|---|---|
| 同时推进多件独立事务 | Supervisor | 持久 Task |
| 多角度审查同一个东西 | Fan-out / Gather | 子 Agent 或持久 Task |
| 批量处理同质任务 | Pipeline | 持久 Task + wait-any |
| 复杂依赖的发布流程 | Graph Workflow | App Server 客户端 |
| 需要质量的代码生成 | Generator-Critic | SubagentStop hook |
| 不确定哪个方案最好 | Fork + Worktree | Worktree |
| 只要一个能跑通就行 | Race | 子 Agent |
| 答案需要交叉验证 | Quorum | 独立上下文 |
三层编排原语：你的工具箱
riba2534 把 Codex 的编排能力分成三层，这个分层极其重要：
第一层：Task 内 Subagent 原语（7 个工具，默认可见）
spawn_agent、list_agents、interrupt_agent、send_message_to_agent 等。这是最常用的层——在一个 Task 里派生和管理子 Agent。
关键参数：fork_turns 控制子 Agent 继承多少主对话上下文（all / none / 数字），这是控制上下文污染最直接的旋钮。
第二层：跨 Task 控制原语（13 个工具，延迟加载）
codex_app 命名空间下的工具——create_thread、fork_thread、list_threads、read_thread、send_message_to_thread、wait_threads、handoff_thread 等。这层是”控制面”这个说法真正成立的地方。
这些工具默认不在工具列表里，需要时 Codex 会动态搜索加载。所以翻会话记录时它们的调用次数很少，但能力一直在。
三个最重要的跨 Task 原语：
create_thread— 建一个持久 Task（非阻塞，三个 target：project / projectless / chatgptWorkCloud）wait_threads— 等最多 8 个线程中第一个完成（wait-any，没有 wait-all）send_message_to_thread— 给另一个会话后台投递消息（对方空闲就开始新工作，正在跑就作为追加方向）
第三层：App Server 协议原语
给外部程序的 API，三个核心对象：Thread、Turn、Item。
outputSchema 是编排里真正值钱的——它把”子任务返回结果然后按结果分支”这件事从靠正则+祈祷变成可校验的数据结构。没有它，Worker 的返回只是一个字符串；有了它，Worker 的返回就是一个能直接进状态机的对象。
跨主机协作：主机只是线程的一个属性
原文里一个非常重要的洞察：
一台 SSH 主机上的 Task 能发现并操作本机的 Task，本机的 Task 同样能操作远端主机上的 Task。主机在这套模型里只是线程的一个属性，起不到隔断的作用。
这意味着什么？你在公司开发机的会话里改完接口，可以直接让本机那个跑着 dev server 的会话打开浏览器验证，验完把结果回传。不需要 SSH 回来，不需要切窗口。这就是”按主机能力路由”的威力。
典型分工：
- Local → UI、浏览器、需要人盯着的前台协作
- 内网开发机 → 需要内网访问的后端工作
- 大内存高核机器 → 大型编译和集成测试
- 常开机器 → 长时间任务和发布验证
- Worktree → 同一仓库的多方案并行
实战建议：从哪开始？
读完 riba2534 的全文，我的建议是从轻到重，逐步深入：
第一步：先用好 Task 内 Subagent
在你日常的 Codex 会话里，遇到需要读大量代码才能得出结论的事，就派子 Agent。给 fork_turns: none 保持上下文干净，要求返回 file:line 级别的证据。
第二步：建一个 Supervisor
找一个 Projectless Task 当 Supervisor，让它帮你管 2-3 个并行的开发任务。体验一下”只跟一个人说话，它帮你协调一切”的感觉。
第三步：把 SOP 写进 Skill
同一个纪律反复出现（比如”先读测试约定、结论必须带 file:line”），就写进自定义 Agent 的 developer_instructions，或挂到 SubagentStart hook 里按类型自动注入。
第四步：尝试跨主机
接一台 SSH 主机进来，把编译任务路由到大内存机器，体验”在哪台机器的会话里说话都不影响你指挥别处”的感觉。
总结
riba2534 这篇文章最大的价值在于：它把 Codex 从”写代码的工具”重新定义为”编排 Agent 的平台”。三层原语 + 八种拓扑 + 跨主机协作，这是一个完整的控制平面。
核心要点：
- Task 是正式成员，Subagent 是临时工——分清这两个，编排就成了一半
- Worktree 是并行的基础——多方案竞赛、Fan-out 都靠它
- wait_threads 是 wait-any，不是 wait-all——等全部完成得自己写循环
- 主机只是线程的一个属性——跨主机协作不需要切窗口
- outputSchema 是把”口语化产出”变成”可校验对象”的钥匙
- 多练。 找 2-3 件有独立支线的事，现在就开几个会话跑一遍
参考来源：riba2534《Codex 进阶指南：作为 Multi-Agent 编排控制平面》 · 写于 2026-08-03
