codex 并行multi-agent 踩坑与使用经验

最近多agent比较火，昨天做了个新项目想着试一下并行任务好不好用，新项目需要写文档、构建数据库、收集数据、写前端、写后端、调试，里面不少工作都可以用并行任务完成。
并行任务开启codex 多代理任务要在config.toml里配置，

[features]
multi_agent = true

[agents]
max_depth = 4
max_threads = 16

除了以上配置，还要对各个子代理进行设置，如果使用默认设置，你将会使用恐怖的gpt-5.1-codex-mini进行并行任务：

这便是我的惨痛经验，子任务都让gpt-5.1-codex-mini完成了，做的又慢又差。
我一开始是使用了以下的错误配置，在config.toml中直接配置，这是学习某位佬友的配置，不过他是在5.4刚出来的时候发的推荐配置，估计是ai给的，这样并不会生效。

[agents.default]
description = "General-purpose helper."
model = "gpt-5.3-codex"
model_reasoning_effort = "high"

[agents.worker]
description = "Do not use this agent, it's silly named and not optimized for any particular role."
model = "gpt-5.2"
model_reasoning_effort = "high"

[agents.explorer]
description = "Fast codebase explorer for read-heavy tasks."
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

[agents.awaiter]
description = "Long-running command and task monitoring role."
model = "gpt-5.4"
model_reasoning_effort = "high"

[agents.reviewer]
description = "Reviewer agent for code reviews and feedback."
model = "gpt-5.4"
model_reasoning_effort = "high"

单独测试了一下，这样配置确实是调用了gpt-5.1-codex-mini。
随后我看了完整的codex文档 Subagents ，并没有推荐放在config.toml里的做法，而是用单文件的配置，放在
~/.codex/agents/<子代理名称>.toml，有几个子代理就建立几个.toml文件，这个.toml文件的格式和config.toml基本完全一致，只是少了模型提供商的地方，使用的时候可以看到codex确实是启动一个新的独立的会话去执行子任务的，因此这个.toml能尽量完善就完善。

文档里提到codex有三种内置子代理：

• default: general-purpose fallback agent.（默认代理，协助主任务用的）
• worker: execution-focused agent for implementation and fixes.（工作代理，完全并行任务用的）
• explorer: read-heavy codebase exploration agent. （探索代码文档代理）

如果不设置的话，这三个子代理的默认模型应该都是gpt-5.1-codex-mini。
<子代理名称>.toml 文件最少得配置3个属性：

• name
• description
• developer_instructions
  但我建议能详细就详细，跑任务的时候可就是单独的会话了，以下是我三个.toml分别的配置：

default.toml:

name = "default"
description = "General-purpose fallback agent."
model = "gpt-5.4"
model_reasoning_effort = "high"
tool_output_token_limit = 40000
developer_instructions = "请始终使用简体中文回答我的问题（解释/推理/总结均用中文）。\n- 代码、命令、报错日志保持原样（不要强行翻译代码/关键字）。\n- 专有名词可保留英文。\n- 除非我明确要求，否则不要切换到其他语言。\n在 Windows 环境执行 shell 命令时，默认优先使用 PowerShell 7（pwsh），较长命令优先使用代码块。若必须使用 Windows PowerShell（powershell.exe），先简要说明原因。"
model_reasoning_summary = "detailed"
model_verbosity = "high"
model_supports_reasoning_summaries = true

service_tier = "fast"

[mcp_servers.mcp-mysql-server]
type = "stdio"
command = "npx"
args = [ "-y", "@f4ww4z/mcp-mysql-server", "mysql://root:123456@127.0.0.1:3306/dianshang" ]

[mcp_servers.chrome-devtools]
command = "npx"
args = [ "-y", "chrome-devtools-mcp@latest", "--isolated=true", "--headless=true" ]
startup_timeout_ms = 20000

[mcp_servers.chrome-devtools.env]
SystemRoot = "C:\\Windows"
PROGRAMFILES = "C:\\Program Files"

worker.toml:

name = "worker"
description = "Execution-focused agent for implementation and fixes."
model = "gpt-5.4"
model_reasoning_effort = "high"
tool_output_token_limit = 40000
developer_instructions = "Implement changes carefully and validate what you changed.\n在 Windows 环境执行 shell 命令时，默认优先使用 PowerShell 7（pwsh），较长命令优先使用代码块。若必须使用 Windows PowerShell（powershell.exe），先简要说明原因。"
model_reasoning_summary = "detailed"
model_verbosity = "high"
model_supports_reasoning_summaries = true

service_tier = "fast"

[mcp_servers.mcp-mysql-server]
type = "stdio"
command = "npx"
args = [ "-y", "@f4ww4z/mcp-mysql-server", "mysql://root:123456@127.0.0.1:3306/dianshang" ]

[mcp_servers.chrome-devtools]
command = "npx"
args = [ "-y", "chrome-devtools-mcp@latest", "--isolated=true", "--headless=true" ]
startup_timeout_ms = 20000

[mcp_servers.chrome-devtools.env]
SystemRoot = "C:\\Windows"
PROGRAMFILES = "C:\\Program Files"

explorer.toml:

name = "explorer"
description = "Read-heavy codebase exploration agent."
model = "gpt-5.4"
model_reasoning_effort = "high"
tool_output_token_limit = 40000
developer_instructions = "Stay in exploration mode. Read, map, and report findings without editing files.\n在 Windows 环境执行 shell 命令时，默认优先使用 PowerShell 7（pwsh），较长命令优先使用代码块。若必须使用 Windows PowerShell（powershell.exe），先简要说明原因。"
model_reasoning_summary = "detailed"
model_verbosity = "high"
model_supports_reasoning_summaries = true

service_tier = "fast"
sandbox_mode = "read-only"

[mcp_servers.mcp-mysql-server]
type = "stdio"
command = "npx"
args = [ "-y", "@f4ww4z/mcp-mysql-server", "mysql://root:123456@127.0.0.1:3306/dianshang" ]

[mcp_servers.chrome-devtools]
command = "npx"
args = [ "-y", "chrome-devtools-mcp@latest", "--isolated=true", "--headless=true" ]
startup_timeout_ms = 20000

[mcp_servers.chrome-devtools.env]
SystemRoot = "C:\\Windows"
PROGRAMFILES = "C:\\Program Files"

这三个文件的内容大都是我从我的config.toml里抄过来的，特别是mcp部分和developer_instructions部分，另外就是推理程度model_reasoning_effort和快速模式service_tier这两个建议也设置一下。

这样设置过后再重启codex运行并行任务，就会使用5.4去跑任务，如果不指定子代理让codex自己去选择的话，完全并行任务并且需要写的话会选择worker子代理，只查文档代码那些会使用
explorer子代理，而单纯协助主代理完成某些脏活累活的单个代理应该就是使用default了。

上图是4个子代理在进行并行任务，worker前面那个应该是codex给子代理的别名，你可以使用nickname_candidates = [“Atlas”, “Delta”, “Echo”] 这样的配置来限定子代理的别名。

除了默认的3种子代理，还可以自定义各种场景的子代理，不过启动的过程要自己提到用什么子代理做什么事情，如果不提的话codex自己会自己决定，可能会落到worker子代理头上。

启动并行任务有两种方法，一种是在~/.codex/AGENTS.md里告诉codex并行任务的启动要素，比如什么时候创建并行任务那些，有个佬友发过这个内容的帖子 codex 全局 AGENTS.md 分享 。我倒是没这么做，因为AGENTS.md给我塞满了codex的各种黑话，来禁止codex发癫，已经有点长了。我是在会话中，使用plan模式的同时，用提示词：“可以使用多子代理完成各自并行任务，要确定两任务的是并行的才能使用子代理并行完成”，codex会给出所有要执行的任务以及并行任务方案，会启动多少个子代理执行什么任务。

如果你的工作场景可以并行执行尽量尝试用子代理来完成，效果飞快。