Codex Multi-Agents 一次走对：配置、原理与避坑实战
更新时间：2026-03-04 适用人群：希望在 Codex 中稳定使用多子代理（multi-agents）的人
先说结论
如果你在使用 multi-agents 时，经常看到类似“我刚才调用方式有误、正在修正并行格式”的长串过程输出，问题通常不在 max_threads，而在调用协议不够刚性。
换句话说：
max_threads = 6只是并发上限，不是每次都要拉满 6 个子代理。- 真正决定稳定性的，是“工具调用格式约束 + 失败降级策略 + 任务拆分质量”。
这篇文章给你一套可直接落地的配置和协议，让 multi-agents 更接近“一次走对”。
你真正需要理解的 3 件事
1) max_threads 是天花板，不是目标值
max_threads = 6 的意思是“最多同时 6 个”，不是“必须 6 个”。
实际并发数由任务可拆分度决定：
实际并发数 = min(可独立子任务数, max_threads)
2) max_depth = 1 能明显减少失控
max_depth = 1 表示主代理可以派子代理，但子代理不能再派“孙代理”。
这会显著减少递归委派、上下文爆炸和调度混乱。
3) 大多数“卡住”是调用参数格式问题
典型报错：
failed to parse function argumentstrailing characters
这通常来自：把多个 JSON 参数对象拼进一次工具调用。不是配置坏了，而是调用形状错了。
我的当前实用配置（已验证）
1) 主配置：~/.codex/config.toml（只列 multi-agents 相关）
[features]
multi_agent = true
[agents]
max_threads = 6
max_depth = 1
[agents.explorer]
description = "Scan code and docs quickly, then summarize findings."
config_file = "agents/explorer.toml"
[agents.reviewer]
description = "Review behavior, risks, and edge cases before changes."
config_file = "agents/reviewer.toml"
[agents.worker]
description = "Implement focused code edits and run checks."
config_file = "agents/worker.toml"2) 角色文件：~/.codex/agents/*.toml
explorer.toml
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "never"
developer_instructions = "You are explorer. Prioritize broad discovery, gather facts quickly, and return concise evidence-backed summaries without making edits."reviewer.toml
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "never"
developer_instructions = "You are reviewer. Focus on correctness, risks, regressions, and missing tests. Provide severity-ordered findings with file references."worker.toml
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
approval_policy = "never"
developer_instructions = "You are worker. Execute scoped code changes, keep edits minimal, and run targeted verification before returning."3) 全局协议：~/AGENTS.md
全局协议建议用英文（跨模型一致性通常更好），关键要点：
- 一子任务 = 一次独立工具调用
- 禁止把多个 JSON 拼到同一个
arguments - 首轮并发建议 3-4（不是固定值）
- 失败后最多重试 1 次，立即降级串行
为什么这么设置：逐项解释 + 出处
| 配置项 | 为什么这样设 | 参考出处 |
|---|---|---|
features.multi_agent = true |
不开启就不会进入多代理调度 | Codex Config / Config Schema |
max_threads = 6 |
给足并发上限；是否跑满由任务拆分决定 | Codex Config Schema |
max_depth = 1 |
抑制链式委派，减少失控和抖动 | Codex Config Schema / Multi-Agents |
config_file 用相对路径 |
提高迁移性（换机器不改绝对路径） | Codex Config Reference |
角色级 sandbox_mode |
探索/审查只读，执行可写，降低误改风险 | Codex Config Schema |
角色级 developer_instructions |
稳定角色边界，减少“什么都做” | Codex Multi-Agents |
| 全局执行协议（失败降级） | 实战中最有效降低“反复纠错循环” | 基于报错模式的工程约束 |
常见误区（你可能已经踩过）
误区 A：我设了 6，为啥只起 2 个？
因为 6 是“最多”，不是“必须”。
误区 B：报错就是配置有问题
不一定。大量报错其实是调用参数格式错误，尤其是 JSON 拼接。
误区 C：并发越高越稳
反过来。首轮并发从 3-4 起步更稳，拿到稳定结果再扩展。
一次走对的提示词模板（可直接用）
请使用多个子代理完成任务，并严格遵守：
1) 首轮并发仅 3-4 个子代理。
2) 每个子代理必须是独立工具调用，禁止把多个 JSON 参数拼到一次调用中。
3) 若出现 parse/arguments/trailing characters 错误，仅允许重试 1 次；仍失败则立即降级串行继续完成。
4) 先输出最终合并结果，再补充简短过程说明。5 分钟自检清单
codex features list | rg 'multi_agent|child_agents_md'
nl -ba ~/.codex/config.toml | sed -n '1,120p'
for f in ~/.codex/agents/*.toml; do echo "--- $f"; nl -ba "$f"; done
nl -ba ~/AGENTS.md | sed -n '1,220p'你应该看到：
multi_agent ... truemax_threads = 6且max_depth = 1- 三个角色文件存在，且
model_reasoning_effort = "high" - 全局协议包含“独立调用、失败降级、首轮 3-4 并发”
参考资料
- Codex Config: https://developers.openai.com/codex/config
- Codex Config Schema: https://developers.openai.com/codex/config-schema.json
- Codex Multi-Agents: https://developers.openai.com/codex/multi-agents
- Codex AGENTS.md: https://developers.openai.com/codex/agents-md
- OpenAI Codex 仓库: https://github.com/openai/codex
- OpenAI 示例（agents_md）: https://github.com/openai/codex/tree/main/codex-rs/examples/agents_md
最后一条建议
如果你的目标是“稳定交付”而不是“理论最大并发”，请把注意力放在：
- 子任务是否独立
- 调用格式是否单一
- 失败是否能立刻降级
这三条比单纯把并发拉满更关键。