官方原文索引： Subagents / Multi-agent Orchestration / Parallel Agent Execution
1. 核心架构与原理解析
Codex 的 Subagents 机制支持主 Agent 拆分子任务并行执行，每个子 Agent 拥有独立的模型配置、沙盒权限和上下文窗口。这标志着从"单 Agent 串行"到"多 Agent 协作"的架构跃迁：
核心参数约束：
| 参数 | 默认值 | 上限 | 工程意义 |
|---|---|---|---|
max_threads | 1 | 10 | 并行子 Agent 数量，直接影响 Token 消耗 |
max_depth | 1 | 3 | 子 Agent 嵌套层级，深度越大调试越困难 |
子 Agent 定义（.codex/agents/*.toml）：
# .codex/agents/security_reviewer.toml
name = "security_reviewer"
description = "专注安全漏洞审查，只读模式"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
像安全审计员一样审查代码。优先查找：
- 注入类漏洞（SQL、Command、LDAP、XPath）
- 敏感数据泄露（日志、异常信息、API 响应）
- 权限越权（水平/垂直越权、IDOR）
- 加密误用（硬编码密钥、弱算法、可预测随机数）
输出格式：
[Risk: Critical/High/Medium] 文件:行号 - 问题描述 - 修复建议
"""典型并行工作流拓扑：
🛠️ 专家视角 / 架构思考： 子 Agent 的本质是用并行上下文换分工清晰度。每个子 Agent 的 Token 消耗独立计算，总成本 = Σ(各子 Agent 消耗)。建议审查类任务并行（省时间），简单修改串行（省成本）。
max_threads = 3是性价比最优的起点。
2. 工程落地与代码示例
主 Agent 触发并行审查
codex "请 review 当前分支，并行使用以下 subagents：
- security_reviewer：检查认证模块的安全漏洞
- test_auditor：分析测试覆盖率和缺失场景
- docs_researcher：核对 API 文档与代码一致性
全部完成后，按严重性排序输出结论，并给出具体文件位置。"批量文件检查（实验性 CSV 批处理模式）
cat > /tmp/review-batch.csv << 'EOFCSV'
path,kind
src/auth.ts,security
src/payment.ts,critical
src/utils.ts,general
EOFCSV
codex "调用 spawn_agents_on_csv：
- csv_path: /tmp/review-batch.csv
- id_column: path
- instruction: '检查 {path} 中的 {kind} 风险，返回 path/risk_level/summary/fix_suggestion'
- output_csv_path: /tmp/review-results.csv"子 Agent 配置中的 MCP 集成
# .codex/agents/docs_researcher.toml
name = "docs_researcher"
description = "核对官方文档，不做代码修改"
model = "gpt-5.4"
sandbox_mode = "read-only"
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"子 Agent 配置集合（完整示例）
# .codex/agents/test_auditor.toml
name = "test_auditor"
description = "测试覆盖率与质量分析"
model = "gpt-5.3-codex-spark"
sandbox_mode = "read-only"
developer_instructions = """
分析测试覆盖的完整性。重点关注：
- 核心路径是否被覆盖
- 边界条件测试（空值、极大值、异常输入）
- 并发场景测试
- 缺失的集成测试和契约测试
输出格式：
[Coverage: Good/Fair/Poor] 文件 - 覆盖率% - 缺失场景
"""# .codex/agents/performance_analyst.toml
name = "performance_analyst"
description = "性能分析与优化建议"
model = "gpt-5.3-codex"
sandbox_mode = "read-only"
developer_instructions = """
分析代码性能瓶颈。重点关注：
- 时间复杂度问题（O(n²) 循环、N+1 查询）
- 内存泄漏（未释放的资源、闭包陷阱）
- I/O 阻塞（同步文件操作、未分页查询）
- 缓存缺失（重复计算、未使用 memoization）
输出格式：
[Severity: High/Medium/Low] 文件:行号 - 问题 - 优化建议 - 预期收益
"""3. 场景深入：子 Agent 在大型项目中的应用
场景：大型 PR 的多维度审查
场景：批量代码现代化
# 对 100+ 个文件进行批量类型注解补充
cat > /tmp/files-to-type.csv << 'EOFCSV'
path,module
src/user/service.ts,user
src/order/service.ts,order
src/payment/service.ts,payment
# ... 更多文件
EOFCSV
codex "调用 spawn_agents_on_csv：
- csv_path: /tmp/files-to-type.csv
- id_column: path
- max_threads: 5
- instruction: '为 {path} 补充 TypeScript 类型注解，确保所有函数参数和返回值都有显式类型'
- output_csv_path: /tmp/type-results.csv"4. 💡 核心避坑与最佳实践 (Takeaways)
- 避免"万能 Agent"陷阱：窄角色、强约束、少漂移。拆分为"代码梳理 → 风险审查 → 文档核对 → 小修复"比单一 Agent 全包更可靠
- 子 Agent 的模型选型策略：审查类用轻量模型（Spark 系列）降低成本，复杂架构分析用满血模型（GPT-5-Codex）
- 嵌套深度限制：
max_depth = 1已覆盖 90% 场景，深层嵌套会导致结果不可预测和调试困难 - 批量模式适合重复性任务：如统一检查多文件的 API 接入写法一致性，不适合需要深度上下文理解的复杂重构
- Token 成本乘以线程数：5 个并行 Agent = 5 倍 Token 消耗，审查场景值得，修改场景需权衡