# 组队 · 配置并调度多个 agent · Codex · 多 Agent 的异步编码工作流 **作者** Aklman · **章节** 06 / 12 · **首发** 2026.08 · **语言** 中文为主, 中英双语 **原文** https://library.aklman.com/books/codex/06-multi-agent **全书 markdown** https://library.aklman.com/books/codex/llms.md **上一章** https://library.aklman.com/books/codex/05-agents-md/llms.md **下一章** https://library.aklman.com/books/codex/07-mcp/llms.md > 本章来自 Aklman · Library, 完整免费阅读。允许 AI 摘读、引用、问答; 转载请保留作者署名与原文链接 (CC BY-NC-ND 4.0, https://library.aklman.com/license)。 --- > 多 Agent 不是把同一句话复制给一群模型,而是让主线程守住目标和决策,把探索、实现、测试与复核交给边界清楚的专门线程。本章从 [agents]、内置 default / worker / explorer 和两级自定义 agent 文件开始,走完手动指派、/agent、Ultra 主动委派、AGENTS.md / skill 触发四条路径,最后用一套可跑配置算清并发、写冲突与 token 账。 多 Agent 不是把同一句需求复制四遍,等四个答案互相投票。它是一套分工:主线程保留目标、约束与最终决策,把能独立完成的探索、测试、实现或复核交给边界清楚的子线程;子线程交回证据摘要,主线程再决定下一步。当前 Codex 默认具备这套能力,但配置、调用路径和成本纪律决定它究竟是生产力,还是一台并行烧 token 的机器。 ### I · 先认人:default、worker、explorer Codex 自带三员。`default` 是通用 fallback,没有更贴切角色时接活;`worker` 偏执行,适合实现和修复;`explorer` 偏只读探索,适合追调用链、清点文件、找测试入口。[^2]不要把它们当三种人格皮肤 —— 角色名是在告诉 orchestrator「这块活的形状」。要查清再动手,先 explorer;方案已定、写入范围清楚,再 worker;任务混合或不值得定制,才交 default。 什么时候自定义?不是每个项目都该先造一支军队。只有当一类工作**反复出现,而且需要不同的模型、权限、工具或固定判断标准**,才值得写 agent 文件。比如安全 reviewer 永远只读、总要高推理;文档核验员只接官方 docs MCP;迁移 worker 能写工作区,但禁止碰数据库。窄而专的 agent 好调度、好验收,也更不容易顺手做掉邻居的活。[^2] --- ### II · 总闸门:[agents] _项目级多 Agent 默认 —— 信任仓库后加载_ ```text title=".codex/config.toml" ```toml [agents] enabled = true max_concurrent_threads_per_session = 4 default_subagent_model = "gpt-5.6-terra" default_subagent_reasoning_effort = "medium" interrupt_message = true ``` ``` 五个键别靠名字猜。`enabled` 是总开关,默认已经是 true。`max_concurrent_threads_per_session` 限制同时保持打开的**子线程**,不含主线程;不写则由 Codex 选默认,旧配置里的 `max_threads` 只是兼容 alias。两个 `default_subagent_*` 是没另行指定时的模型与推理力度。`interrupt_message` 决定打断子线程时是否把一条模型可见的中断消息记进上下文,也默认 true。[^3] 解析顺序也要记住。一次 spawn 明说的值先赢;否则看 `[agents]` 默认;再没有才继承父线程。自定义 agent 文件若显式写了 `model` 或 `model_reasoning_effort`,文件里的值生效。其他会话设置没写就继承父线程。还有一层实时边界:父线程这轮临时切过的权限模式会重新施加到孩子身上,不能靠 agent 文件绕过当前会话的安全选择。[^2] --- ### III · 自定义 agent:一个 TOML,一份职责 个人 agent 放 `~/.codex/agents/`,跟着你跨项目走;项目 agent 放仓库里的 `.codex/agents/`,随团队版本控制。每个 TOML 至少写 `name`、`description`、`developer_instructions`。文件名只是惯例,`name` 才是身份来源;如果它叫 explorer,就覆盖内置 explorer。[^2]下面是一套能直接放进项目的三员配置: #### repo_explorer.toml ```toml name = "repo_explorer" description = "只读扫描代码路径、测试入口和影响面;动手前用。" model = "gpt-5.6-terra" model_reasoning_effort = "medium" sandbox_mode = "read-only" developer_instructions = """ 只做证据驱动的探索。用文件和 symbol 定位结论。 返回精炼摘要,不要粘原始日志,不要修改文件。 """ ``` #### implementation_worker.toml ```toml name = "implementation_worker" description = "方案确认后做一个边界清楚的实现或修复。" model = "gpt-5.6" model_reasoning_effort = "medium" sandbox_mode = "workspace-write" developer_instructions = """ 只实现主线程明确分配的范围。保留无关改动。 完成后跑最窄的相关检查,返回改动摘要与验证证据。 """ ``` #### reviewer.toml ```toml name = "reviewer" description = "只读验收 diff,优先找正确性、安全和测试缺口。" model = "gpt-5.6-terra" model_reasoning_effort = "high" sandbox_mode = "read-only" developer_instructions = """ 像代码所有者一样审查。先报真实风险,附文件定位和复现步骤。 忽略纯风格偏好;没有 actionable finding 就明确说没有。 """ [mcp_servers.openaiDeveloperDocs] url = "https://developers.openai.com/mcp" ``` 这三份也展示了每 agent 的配置面:model、`model_reasoning_effort`、`sandbox_mode` 和 `mcp_servers` 都能独立设。`skills.config` 也能放进单个 agent 文件,用于按 SKILL.md 的**绝对路径**启用或禁用一项已安装 skill;路径因机器而异,所以不把伪路径塞进这份可直接运行的仓库示例。没写的 MCP 与 skill 设置从父线程继承。[^2] _只让这个 agent 覆写某项已安装 skill 的启用状态_ ```text title="~/.codex/agents/reviewer.toml · 可选追加" ```toml [[skills.config]] path = "/Users/you/.agents/skills/acceptance/SKILL.md" enabled = true ``` ``` --- ### IV · 四条调用路径,别混成一条 - **手动指派**: 在 prompt 里点名角色、拆分方式、等待条件和要回的摘要。这是 Codex 本地与 Work 在大多数 intelligence level 上最确定的入口。 - **/agent**: CLI 里查看、切换 active / done 子线程。它是线程管理入口,不是一句 spawn 命令;先要求委派,再用它检查。 - **Ultra 主动委派**: 在 eligible account 与受支持模型上,Work 的 Ultra 可判断并行确有收益时主动派 agent;其他档仍应明确要求。 - **AGENTS.md / skill 触发**: 项目规矩或被触发的 skill 可以明确要求使用 subagents;它适合把稳定流程固化,不适合藏一次性的临时决定。 **提示词 · Codex · Multi-Agent** ```text 请用多 agent 完成这项任务。 目标:<要交付什么> 探索:派 <数量> 个 repo_explorer,分别检查 <互不依赖的范围>;只读,返回文件定位与风险摘要。 实现:等所有探索完成,由主线程合并方案;只派一个 implementation_worker 修改 <允许范围>。 验收:实现后派 reviewer 对照 <测试 / 安全 / 兼容标准> 独立复核。 边界:<不能改 / 不能访问 / 需要审批的动作> 返回:等所有 agent 完成,只给结论、证据、未决风险和最终 diff 摘要,不要倾倒原始日志。 ``` **示例** ```text 请用多 agent 修复设置页保存后偶发回滚的问题。 目标:找到根因并提交最小修复,不改变 API schema。 探索:派两个 repo_explorer;一个追设置页状态与请求链,一个查相关测试和最近改动;都只读,返回文件定位与可复现条件。 实现:等两份摘要后由主线程定方案,只派一个 implementation_worker 改设置页与直接相关测试。 验收:实现后派 reviewer 检查竞态、错误处理、回归覆盖,并核对官方框架 API。 边界:不改数据库、不碰无关格式、不启动破坏性命令。 返回:等全部完成,给根因、改动、测试证据、review finding 与剩余风险。 ``` --- ### V · 并行有收益,也有账 最稳的起点是**读密集型并行**:探索不同子系统、跑互不依赖的测试、清点迁移影响面、分析日志、核对文档。它们很少争同一个文件,产物又能压成摘要。官方也明确建议从这里开始。[^4]写密集型要反过来保守:多个 worker 同时改同一工作区,省下的等待很可能换成冲突、覆盖和重新协调。默认用「多路读、单路写、独立复核」;真要多路写,先给每路独立 worktree 或 cloud task。 | 任务形状 | 默认选择 | 为什么 | |---|---|---| | 一件复杂活,多路调查 | subagents | 共享目标,摘要回主线程 | | 几件独立改动,都要碰文件 | 多个 worktree | 隔离检出,避免写冲突 | | 离机、长跑、要 PR 收回 | 多个 cloud tasks | 隔离容器与远程生命周期 | | 一条短而串行的小改 | 单 agent | 协调成本大于并行收益 | > 最后算 token 账。每个子 agent 都有自己的输入、cached input、输出和工具往返;多 agent 相对可比的单 agent 任务通常更烧 token。[^1]Ultra 也没有一行特殊折扣 —— 它若多派 agent,这些 agent 的 token 一并计入任务消耗。[^5]控制账单的四个旋钮是:只拆真正独立的活、限制并发、给轻量探索用 Terra / Luna、要求摘要而不是原始输出。并行先优化的是**墙上时间**,不是总 token;别把「快 40%」误写成「省 40% credits」。 动手 · 跑一次有边界的三段接力: - **并行读**: 选一项跨两个子系统的问题,派两个 repo_explorer,明确只读范围和摘要格式。用 /agent 打开其中一条线程,确认它在查证而不是抢先改。 - **串行写**: 等两份结果齐全,由主线程消除矛盾并定方案,只让一个 implementation_worker 落地。写入变多时不要再加 worker,改用 worktree 隔离。 - **独立验**: 让 reviewer 只看目标、diff 与测试证据,不要把 worker 的自我评价当结论。主线程最后合并 finding,决定接受、返工或留下待核项。 > 主线程做决定, > 子线程交证据 ## 引用与参考 01 · OpenAI · Subagents —— 当前 Codex release 默认启用 subagent workflow,桌面应用、CLI 与 IDE 扩展都会显示子线程;Work 对 eligible account 开放。普通 intelligence level 要显式要求委派,Ultra 在 eligible account 与受支持模型上可主动委派。每个子 agent 都会独立做模型与工具工作,所以比可比的单 agent 任务消耗更多 token。截至 2026-08-05。 (OpenAI · Subagents) 02 · OpenAI · Subagents / Custom agents —— 内置角色是 default、worker、explorer。个人自定义 agent 放 ~/.codex/agents/,项目级放 .codex/agents/;每个 TOML 必填 name、description、developer_instructions,也可覆写 model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config。同名自定义 agent 覆盖内置角色。截至 2026-08-05。 (OpenAI · Custom agents) 03 · OpenAI · Subagents / Global settings —— [agents] 支持 enabled、max_concurrent_threads_per_session、default_subagent_model、default_subagent_reasoning_effort、interrupt_message。enabled 与 interrupt_message 默认 true;并发上限不含主线程,max_threads 是旧 alias。显式 spawn 参数优先于 [agents] 默认;agent 文件显式 model / effort 又有自己的优先级。截至 2026-08-05。 (OpenAI · Global subagent settings) 04 · OpenAI · Subagents / Why subagent workflows help —— 官方建议从探索、测试、triage、总结等读密集型工作开始;子 agent 应回摘要而不是原始中间输出。多个 agent 同时写代码更容易冲突并增加协调开销。截至 2026-08-05。 (OpenAI · Why subagents help) 05 · OpenAI · Codex rate card —— credits 按模型的 input / cached input / output token 计;Ultra 不是独立费率行,它可能运行额外 agent,实际消耗仍由主任务与所有 agent 的 token 合计决定。截至 2026-08-05。 (OpenAI Help · Codex rate card) --- *组队 · 配置并调度多个 agent · Codex · 多 Agent 的异步编码工作流 · Aklman 著 · CC BY-NC-ND 4.0 · https://library.aklman.com/books/codex/06-multi-agent*