Codex 配置并行 Multi-Agent

把 Multi-Agent 和子代理配置写完整后，Codex 才能把适合拆开的任务同时推进。

这篇文档适合谁

适合刚开始接触 Codex，希望把查资料、读代码、修改实现、整理文档分开处理的使用场景。

先建立一个整体印象

Multi-Agent 可以理解成一种“分工处理”的方式：主代理负责拆分任务，子代理分别处理各自的小任务，最后再把结果汇总。

例如，一个新项目同时包含文档整理、数据库准备、前端页面调整和接口检查时，其中不少部分互相独立，这时就很适合并行处理。等待时间通常会明显减少。

这里先记住两件事：

先在 config.toml 里开启 multi_agent
再给子代理补上各自的配置文件

只有第一步，没有第二步，Codex 依然可以启动并行任务，但子代理使用的模型、行为规则和工具设置通常比较基础。复杂任务里，效果往往没有单独配置时稳定。

第一步：开启 Multi-Agent

config.toml 常见位置如下：

text

Linux 与 macOS：~/.codex/config.toml
Windows：C:\Users\用户名\.codex\config.toml

先加入下面这段配置：

toml

[features]
multi_agent = true

[agents]
max_depth = 3
max_threads = 8

这两个参数分别表示什么

配置项	作用	新手建议
`max_depth`	子代理还能继续拆分任务的层级	先用 `3`
`max_threads`	同时运行的子代理数量上限	先用 `8`

参数可以先从小一些开始

如果设备性能一般，先用 max_depth = 2 与 max_threads = 4 会更平稳。如果经常处理大任务，再逐步提高会更容易观察变化。

第二步：认识三个内置子代理

Codex 默认带有三种常见子代理：

子代理	用途	适合处理的事情
`default`	通用辅助代理	零散的小任务、补充说明、简单整理
`worker`	执行型代理	编写实现、修复问题、批量修改
`explorer`	阅读型代理	阅读代码、查文档、整理信息

可以先这样理解：

default 像通用助手
worker 负责动手处理
explorer 负责先看、先查、先整理

第三步：为子代理单独写配置

子代理配置文件可以放在两个位置：

text

全局目录
Linux 与 macOS：~/.codex/agents/<子代理名称>.toml
Windows：C:\Users\用户名\.codex\agents\<子代理名称>.toml

项目目录
.codex/agents/<子代理名称>.toml

两种方式都可以生效。

如果希望所有项目共用同一套配置，放在全局目录会更省事。如果希望某个项目使用专门的规则，放在项目目录会更合适。

每个文件至少要有这几个字段

字段	作用
`name`	子代理名称
`description`	子代理职责简介
`developer_instructions`	子代理收到任务后要遵守的规则

实际使用时，通常还会补充 model、model_reasoning_effort、service_tier 等字段。原因很简单：子代理是独立会话，说明越清楚，表现通常越稳定。

`default.toml` 示例

toml

name = "default"
description = "General-purpose fallback agent."
model = "gpt-5.4"
model_reasoning_effort = "high"
tool_output_token_limit = 40000
developer_instructions = """
请始终使用简体中文回答。
代码、命令、报错日志保持原样。
专有名词可以保留英文。
除非有明确要求，否则保持当前语言。
在 Windows 环境执行 shell 命令时，优先使用 PowerShell 7。
"""
model_reasoning_summary = "detailed"
model_verbosity = "high"
model_supports_reasoning_summaries = true
service_tier = "fast"

[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` 示例

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 carefully and validate every change.
在 Windows 环境执行 shell 命令时，优先使用 PowerShell 7。
"""
model_reasoning_summary = "detailed"
model_verbosity = "high"
model_supports_reasoning_summaries = true
service_tier = "fast"

[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` 示例

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.
在 Windows 环境执行 shell 命令时，优先使用 PowerShell 7。
"""
model_reasoning_summary = "detailed"
model_verbosity = "high"
model_supports_reasoning_summaries = true
service_tier = "fast"
sandbox_mode = "read-only"

[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"

这些字段里，哪些最值得先看

对新手来说，先理解下面五项就够用了：

model
指定子代理使用哪个模型。任务更复杂时，可以换成更强的模型。
developer_instructions
相当于给子代理写一份长期规则，例如回答语言、命令习惯、修改边界。
model_reasoning_effort
表示推理强度。值更高时，分析通常更细，但资源消耗也会更大。
service_tier
表示服务档位。示例里使用 fast，适合日常高频使用。
sandbox_mode
常见于阅读型子代理。read-only 表示只读，更适合查资料、看代码、做分析。

先记住一件事

如果三个子代理都没有单独配置，Codex 一般会使用默认设置。处理简单任务通常够用，处理复杂任务时，单独配置往往会更省时。

第四步：重启 Codex，让配置生效

完成 config.toml 和子代理文件后，重启一次 Codex，再开始新的会话。这样能确保新配置被完整读取。

第五步：让 Codex 开始并行处理任务

常见方式有两种。

方式一：在 `AGENTS.md` 里提前写规则

适合希望长期固定使用习惯的情况，例如：

什么情况下适合启用并行任务
哪些任务可以拆分
子代理如何分工
哪些操作需要先确认

下面是一份简洁版 AGENTS.md 示例：

# 并行任务协作规范

## 何时使用并行任务

当任务之间互相独立，且同时处理能够减少等待时间时，优先使用子代理并行完成。

## 分工方式

1. `worker` 负责实现、修复、批量修改
2. `explorer` 负责阅读、查找、整理、分析
3. `default` 负责补充说明和辅助任务

## 使用要求

1. 先判断任务之间是否互相独立
2. 避免同时修改同一个文件
3. 先汇总各子代理结果，再继续下一步
4. 危险操作先征求确认

方式二：在当前会话中主动提示

这种方式更常见，尤其适合临时任务。在 plan 模式里，可以补上一句类似的提示：

text

可以把互相独立的任务拆开处理。先判断哪些部分能够同时进行，再分别交给合适的子代理，最后汇总结果。

Codex 判断任务适合并行时，通常会先拆分任务，再说明准备启动几个子代理，以及各自负责的内容。

Codex 通常如何分配任务

任务类型	常见分配
编写实现、修复问题	`worker`
阅读代码、查文档、整理信息	`explorer`
零散辅助任务	`default`

如果希望分配更稳定，可以在指令里明确写出子代理名称和职责。

哪些任务适合并行

下面几类事情通常很适合交给多个子代理同时处理：

同时阅读多个目录
同时整理多份文档
同时检查前端、后端和数据库配置
同时比较几种实现方案

哪些任务暂时更适合顺序处理

所有步骤必须前后紧密衔接
多个任务要同时修改同一个文件
任务本身很小，拆开后反而更慢

常见疑问

为什么已经开了 `multi_agent`，效果还是一般

通常有三种原因：

子代理没有单独配置
任务本身不适合拆分
并发参数和设备性能不匹配

为什么 `explorer` 建议加 `read-only`

因为 explorer 更适合“看”和“整理”，只读设置能减少误修改，阅读场景也会更清晰。

为什么建议把说明写详细一些

因为每个子代理都是独立会话。说明越清楚，子代理越容易保持稳定的语言、工具习惯和任务边界。

一份适合新手的最小配置

如果刚开始接触，可以先用下面这组：

toml

[features]
multi_agent = true

[agents]
max_depth = 2
max_threads = 4

再配上三个最基本的子代理文件：

text

~/.codex/agents/default.toml
~/.codex/agents/worker.toml
~/.codex/agents/explorer.toml

先让并行能力稳定运行，再逐步补充模型、工具和规则设置，会更容易看清每个配置项的作用。✨

Codex 配置并行 Multi-Agent ​

先建立一个整体印象 ​

第一步：开启 Multi-Agent ​

这两个参数分别表示什么 ​

第二步：认识三个内置子代理 ​

第三步：为子代理单独写配置 ​

每个文件至少要有这几个字段 ​

default.toml 示例 ​

worker.toml 示例 ​

explorer.toml 示例 ​

这些字段里，哪些最值得先看 ​

第四步：重启 Codex，让配置生效 ​

第五步：让 Codex 开始并行处理任务 ​

方式一：在 AGENTS.md 里提前写规则 ​

方式二：在当前会话中主动提示 ​

Codex 通常如何分配任务 ​

哪些任务适合并行 ​

哪些任务暂时更适合顺序处理 ​

常见疑问 ​

为什么已经开了 multi_agent，效果还是一般 ​

为什么 explorer 建议加 read-only ​

为什么建议把说明写详细一些 ​

一份适合新手的最小配置 ​

Codex 配置并行 Multi-Agent

先建立一个整体印象

第一步：开启 Multi-Agent

这两个参数分别表示什么

第二步：认识三个内置子代理

第三步：为子代理单独写配置

每个文件至少要有这几个字段

`default.toml` 示例

`worker.toml` 示例

`explorer.toml` 示例

这些字段里，哪些最值得先看

第四步：重启 Codex，让配置生效

第五步：让 Codex 开始并行处理任务

方式一：在 `AGENTS.md` 里提前写规则

方式二：在当前会话中主动提示

Codex 通常如何分配任务

哪些任务适合并行

哪些任务暂时更适合顺序处理

常见疑问

为什么已经开了 `multi_agent`，效果还是一般

为什么 `explorer` 建议加 `read-only`

为什么建议把说明写详细一些

一份适合新手的最小配置