Codex多Agent调度
Codex CLI 的并行任务执行系统，让 Codex 从"单线程 AI 程序员"变成"AI 开发团队调度中心"。主 Agent 将复杂任务分解后，派遣多个子 Agent 并行执行，收集汇总结果。
核心价值
单 Agent 面临上下文窗口有限、顺序执行、单点失败三大局限。Multi-Agent 解决：任务分解（每个 subagent 专注较小上下文）、并行执行、专业分工、隔离失败（subagent 失败不影响主流程）。
核心工具集（feature flag: multi_agents）
| 工具 | 功能 |
|---|---|
spawn_agent |
派遣单个 subagent，指定 role/prompt/workspace，返回 agent_id |
spawn_agents_on_csv |
批量派遣（每行 CSV = 一个任务），适合批量同构任务 |
send_input(id, msg) |
向运行中的 subagent 追加指令 |
wait_agent(id) |
阻塞等待 subagent 完成，返回结果摘要 |
resume_agent(id) |
恢复暂停的 subagent |
close_agent(id) |
终止 subagent，释放资源 |
list_agents() |
列出所有 subagent 及其状态 |
角色系统（Role Configuration）
Subagent 有专业角色，在 config.toml 中定义：
[agents.coder]
guidance = "专注实现，不跨模块边界"
display_names = ["Alice", "Bob", "Charlie"] # 多实例随机昵称
[agents.reviewer]
guidance = "关注安全、性能、API 设计，只提建议不改代码"
[agents.documenter]
guidance = "生成技术文档、README、架构决策记录"
地址系统
基于路径的可读地址（2026 年引入）：
/root → 主 Agent
/root/agent_a → 主 Agent 的 subagent
/root/agent_a/sub_1 → 嵌套 subagent
人类可读（vs UUID），便于 TUI 中展示 agent 树结构。
并发与资源限制
[agents]
max_concurrent_agents = 6 # 默认 6，防止资源失控
max_nesting_depth = 1 # 默认 1，subagent 不能再派 subagent
default_worker_timeout = 1800 # 默认 30 分钟超时
嵌套深度限制为 1 是刻意的工程决策：防止递归爆炸（token 呈指数增长），保持可调试性。
典型场景：spawn_agents_on_csv
批量同构任务（50 个 API endpoint 各写测试、30 个模块迁移框架）： 1. 主 Agent 枚举任务目标 → 生成 CSV → 调用 spawn_agents_on_csv 2. 每个 Worker Agent 独立上下文、独立沙箱 3. 主 Agent wait 所有 worker → 汇总报告
DevDay 2025 案例：7 个终端同时跑 7 个 Codex 实例，各自开发一款 Phaser.js 游戏，开发者只做审批和方向把控——开发者带宽的杠杆化。
降低不确定性的机制
| 不确定性场景 | Multi-Agent 的应对 |
|---|---|
| 单个 Agent 上下文不够 | 分解任务，每个 subagent 专注小上下文 |
| 任务相互依赖导致顺序问题 | wait_agent 显式依赖同步 |
| 某个子任务 Agent 出错 | 局部失败隔离，不影响其他 subagent |
| Agent 角色不专业，泛化处理 | Agent角色系统</td> </tr> <tr> <td>资源失控，Token 爆炸</td> <td>max_concurrent_agents + timeout 硬限制</td> </tr> <tr> <td>不知道 subagent 在做什么</td> <td>路径地址系统 + TUI agent 树展示</td> </tr> </tbody> </table> <h2 id="_5">工程哲学</h2> <blockquote> <p><strong>Multi-Agent 把"人类团队的分工协作"映射到 AI Agent 层面</strong>。好的团队有架构师、工程师、Review 者各司其职。Role 系统让不同 subagent 各自专注，用结构化分工取代"一个 Agent 包揽一切"的脆弱模式。最重要的工程决策：<strong>嵌套深度限制为 1</strong>——简单、可预测、易调试，比理论上的无限灵活更重要。</p> </blockquote> <h2 id="_6">来源</h2> <ul> <li>[[raw/articles/ai-tools/codex/07_codex_multi_agent.md |