Codex Subagent 配置与使用指南：目录、TOML 与并行任务

Sat, 11 Jul 2026 00:00:00 +0000

Codex Subagent 配置与使用指南：目录、TOML 与并行任务

当一个任务同时包含代码探索、风险审查、测试验证和文档核对时，让主会话从头到尾串行处理并不总是最高效。

Codex 的 Subagent（子代理）机制允许主代理把相互独立的工作交给不同代理线程：有人负责查代码，有人负责跑测试，有人负责核对文档，最后再由主代理汇总结果。

但 Subagent 不是“开得越多越快”。任务能不能独立、权限有没有收紧、输出格式是否明确，往往比代理数量更重要。

这篇只讲 Codex 自身的 Subagent 配置与使用。如果你想比较 Codex 和 Claude Code 的 Agent 设计差异，可以看 Codex 也能定义 Agent：和 Claude Code Agent 到底差在哪；如果你其实想找的是 SKILL.md 应该放在哪里，则看 Codex 的 skill 放在哪、怎么被发现。

先说结论

Codex 的 Subagent 可以理解成：由主代理创建、在独立线程中执行一个明确子任务、完成后把结果交还给主代理的工作单元。

Codex 自带三种基础 Agent：

Agent	主要用途
`default`	通用后备代理
`worker`	实现、修复和执行型任务
`explorer`	以阅读和代码库探索为主的任务

如果内置角色不够用，可以通过 TOML 文件定义自定义 Agent：

范围	目录
用户级	`~/.codex/agents/<name>.toml`
项目级	`.codex/agents/<name>.toml`

一个自定义 Agent 至少需要 name、description 和 developer_instructions 三个字段。模型、推理强度、沙箱、MCP 和 skill 开关等配置可以按需覆盖，不写时通常从父会话继承。

核心概念：Subagent 解决什么问题

Subagent 最适合两类任务。

第一类是可以并行的独立调查。例如审查一个分支时，把安全风险、测试缺口和可维护性问题交给三个代理分别检查。

第二类是需要隔离关注点的专项工作。例如让只读代理探索代码，让另一个代理运行测试，避免每个代理都同时修改文件。

可以把整个过程理解成：

1
2
3
4
5
6


主代理
├── explorer：定位相关代码和调用链
├── reviewer：检查风险和回归
└── test-runner：运行测试并整理失败信息
 ↓
主代理等待结果、处理冲突、给出最终结论

这里最重要的不是“多代理”三个字，而是主代理负责拆分和汇总，子代理负责边界明确的子任务。

什么任务适合，什么任务不适合

适合交给 Subagent 的任务通常有这些特点：

各子任务可以独立完成，不必频繁等待彼此结果。
主要工作是阅读、搜索、测试、日志分析或资料核对。
每个子任务能用一句话说清输入、范围和输出。
主代理可以根据多个结果做最终取舍。

不适合直接并行的任务包括：

多个代理同时修改同一组文件。
第二步必须依赖第一步产生的代码或结论。
任务很小，拆分和汇总的成本高于直接完成。
目标本身还不清楚，代理之间容易各自理解成不同方向。

一个实用原则是：先并行只读调查，再由一个明确的实现代理落地修改。 这样比让多个代理同时施工更容易控制冲突。

自定义 Agent 放在哪里

个人长期复用的 Agent 放在：

1

~/.codex/agents/

例如：

1

~/.codex/agents/reviewer.toml

需要跟仓库一起版本控制、供团队共用的 Agent 放在：

1

<repo>/.codex/agents/

例如：

1
2
3
4
5
6
7
8


my-project/
├── .codex/
│ ├── config.toml
│ └── agents/
│ ├── code-mapper.toml
│ ├── reviewer.toml
│ └── test-runner.toml
└── src/

每个 TOML 文件定义一个自定义 Agent。项目级配置适合写入与仓库结构、测试命令和团队职责相关的约束；用户级配置更适合通用角色。

最小 TOML 怎么写

一个最小可用的代码审查 Agent 可以这样写：

1
2
3
4
5
6
7
8


name = "reviewer"
description = "代码审查代理，负责发现正确性、安全性、行为回归和测试缺口。"
developer_instructions = """
你只负责审查，不修改代码。
优先报告能够复现或能从代码路径证明的问题。
每个问题都要给出文件位置、影响和建议验证方法。
如果没有发现实质问题，明确说明未发现，而不是凑数量。
"""

三个必填字段各自承担不同职责：

字段	作用
`name`	Codex 创建或引用该 Agent 时使用的身份名称
`description`	说明什么情况下适合使用这个 Agent
`developer_instructions`	定义它具体怎样工作、做什么和不做什么

Codex 以 name 作为身份来源，文件名只是方便管理的约定。虽然 foo.toml 可以写成 name = "bar"，但让文件名与 name 保持一致更容易排查。

常用可选配置

自定义 Agent 文件还可以使用正常 Codex 会话配置中的部分字段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


name = "code_mapper"
description = "只读代码探索代理，负责定位入口、调用链和受影响文件。"
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
nickname_candidates = ["Atlas", "Delta", "Echo"]

developer_instructions = """
先定位代码，不修改文件。
输出入口、主要调用链、状态变化和建议继续检查的文件。
只报告有证据支持的路径。
"""

常见字段包括：

字段	作用
`model`	为该 Agent 指定模型
`model_reasoning_effort`	调整推理强度
`sandbox_mode`	限定为只读或允许工作区写入
`mcp_servers`	给该 Agent 配置专用 MCP 服务
`skills.config`	控制该 Agent 可使用的 skill
`nickname_candidates`	为多个同类实例提供便于区分的显示昵称

nickname_candidates 只影响界面展示，不改变 Agent 的真实身份；Codex 仍然通过 name 创建和引用它。

继承规则：不写不等于没有

自定义 Agent 不是从一张完全空白的配置开始运行。官方把 Agent TOML 作为创建会话时叠加的配置层，未覆盖的可选设置通常从父会话继承。

这意味着：

不写 model，通常沿用父会话的模型选择。
不写 sandbox_mode，不会自动变成只读代理。
父会话启用的 MCP 或其他配置，子代理可能继续继承。
在 Agent 文件中显式配置的值，会用于覆盖对应设置。

因此，涉及安全边界时不要依赖想象中的默认值。只做探索或审查的 Agent，建议明确写：

1

sandbox_mode = "read-only"

需要修改代码的 Agent 再单独授予工作区写入能力。

怎样触发 Subagent 工作流

最可控的方式是在任务中明确要求使用 Subagent，并说明如何拆分：

1
2
3


请使用并行 Subagent 审查当前分支：
一个负责安全风险，一个负责测试缺口，一个负责可维护性。
等待三个 Agent 全部完成后，再按严重程度汇总，并附文件位置。

如果已经定义了自定义 Agent，可以直接点名角色：

1
2
3


让 code_mapper 先定位这次故障涉及的前后端调用链，
让 reviewer 独立检查回归风险。
等待两者完成后汇总结论，暂时不要修改代码。

不同 Codex 产品界面、模型模式和项目规则可能影响是否会主动委派。对需要稳定复现的工作流，建议显式写出：

要不要使用 Subagent。
使用几个 Agent，分别承担什么角色。
哪些任务并行，哪些任务必须串行。
是否允许修改文件。
主代理何时等待、怎样汇总结果。

怎样写好一个子任务

一个好的子任务至少包含五个部分：

目标：要解决什么问题。
范围：检查哪些目录、文件、接口或日志。
边界：是否允许编辑、是否允许扩大调查范围。
输出：需要结论、证据、文件位置还是测试结果。
完成条件：什么时候可以停止并返回主代理。

例如，下面这条比“看看前端有没有问题”更稳定：

1
2
3
4


只读检查 web/settings 下保存配置的完整调用链。
定位按钮事件、状态更新、API 请求和错误处理。
不要修改文件。
返回涉及的文件、关键函数、最可能的失败点，以及需要主代理验证的两项证据。

Subagent 拿到的是被委派的上下文，不应该假设它自动理解主会话中所有隐含目标。任务说明越具体，返回结果越容易被主代理直接使用。

控制并发和嵌套深度

全局或项目级的 Subagent 运行参数写在 config.toml 的 [agents] 下：

1
2
3


[agents]
max_threads = 6
max_depth = 1

主要配置包括：

字段	作用	官方当前默认值
`agents.max_threads`	同时保持打开的 Agent 线程上限	`6`
`agents.max_depth`	Agent 继续创建下一级 Agent 的最大深度	`1`
`agents.job_max_runtime_seconds`	批量 CSV Worker 的默认超时	未设置时单次调用默认 1800 秒
`agents.interrupt_message`	中断时是否在 Agent 上下文中记录可见消息	`true`

根会话深度是 0。默认 max_depth = 1 表示根代理可以创建直接子代理，但子代理不能继续无限向下创建孙代理。

不要为了“更智能”随意提高嵌套深度。层级越深，越容易出现任务重复扩散，Token、等待时间和本机资源消耗也会同步增加。大多数代码任务保留一层子代理已经足够。

一个更稳的实际工作流

假设要排查“设置弹窗保存失败”，可以分成三步。

第一步：并行调查

browser_debugger：复现界面问题，记录操作步骤、控制台和网络请求。
code_mapper：只读定位按钮、状态管理、API 请求和后端处理链路。

这两个任务互不依赖，可以并行执行，而且都不修改代码。

第二步：主代理汇总

主代理等待两个结果，对比“界面实际行为”和“代码预期路径”，确定故障点。如果结论冲突，先补证据，不急着进入实现。

第三步：单一 Agent 修改

确认原因后，只让一个 worker 或专用实现 Agent 修改代码和运行针对性测试。这样可以避免多个代理同时触碰相同文件。

完整请求可以写成：

1
2
3
4


调查设置弹窗保存失败的问题。
先让 browser_debugger 复现并收集浏览器证据，同时让 code_mapper 只读梳理调用链。
等待两者完成后，由主代理判断根因。
只有根因明确后，才让一个 worker 实施最小修复并运行相关测试。

Subagent 与 Skill 的关系

两者可以配合，但不是同一种能力：

对比项	Subagent	Skill
核心作用	独立执行一个被委派的子任务	提供可复用的任务工作流
主要文件	`.codex/agents/*.toml`	`.agents/skills/<name>/SKILL.md`
是否有独立线程	有	没有，通常由当前 Agent 读取并执行
是否可配置模型和沙箱	可以	Skill 本身不等同于独立会话配置
典型场景	并行探索、专项审查、测试、日志分析	发布流程、文章封面发布、固定检查清单

一个 Subagent 可以被配置为使用某些 Skills，但“给 Agent 加一个 Skill”不等于又创建了一个 Subagent。

还要注意 Skill 目录内部可能出现 agents/openai.yaml。它用于描述该 Skill 的展示、依赖或调用策略，不是项目级 .codex/agents/*.toml 自定义 Agent，不能混为一谈。

常见问题与解决方案

自定义 Agent 是不是放进去就会自动运行

不是。TOML 文件只是让 Codex 知道存在这样一个角色。是否创建它，仍取决于当前任务、产品行为和委派指令。需要确定使用时，直接在提示词中点名。

项目级和用户级应该选哪个

与仓库结构、团队命令、项目权限有关的角色放项目级 .codex/agents/；跨仓库通用的个人角色放 ~/.codex/agents/。

文件名必须和 name 一样吗

不是硬性要求，name 才是身份来源。但两者保持一致更方便维护，也能减少点名时的混淆。

多开几个 Agent 一定更快吗

不一定。只有互相独立的任务才容易获得并行收益。多个 Agent 修改同一位置、反复读取同一批文件，或者需要频繁互相等待时，通常只会增加成本和冲突。

子代理能不能继续创建子代理

由 agents.max_depth 决定。默认值 1 允许根会话创建一层直接子代理，但不允许继续向下递归。除非确实需要分层委派，否则建议保留默认值。

怎样避免 Subagent 擅自修改代码

同时做两件事：在 TOML 中设置 sandbox_mode = "read-only"，并在 developer_instructions 和具体子任务里明确写“只读检查，不修改文件”。权限限制负责硬边界，文字说明负责工作目标。

总结

用好 Codex Subagent，关键不在于创建多少 Agent，而在于四件事：

第一，角色要窄。一个 Agent 只承担一种清楚的职责。

第二，任务要能独立。优先并行探索、测试、日志分析和文档核对，不要让多个 Agent 同时修改同一片代码。

第三，权限要明确。只读任务显式使用 sandbox_mode = "read-only"，需要施工时再交给单一实现 Agent。

第四，并发要受控。保留合理的 max_threads 和默认一层嵌套，避免代理递归扩散。

当主代理负责拆分、等待和汇总，Subagent 才真正是在节省时间，而不是把一个问题变成更多上下文和更多冲突。

写在最后

这篇解决的是 Codex Subagent 自身的配置和使用。如果你要继续比较两家 Agent 在自动委派、权限模型和工程化能力上的差异，可以接着看 Codex 也能定义 Agent：和 Claude Code Agent 到底差在哪。

Codex 的 Subagent 仍在快速迭代，尤其是不同产品界面的主动委派行为、批量任务和管理入口。本文基于 2026 年 7 月的官方文档整理，升级版本后建议再次核对官方说明。

参考资料：

Subagents – Codex | OpenAI Developers

TOML on 记录点滴 - 分享

Codex Subagent 配置与使用指南：目录、TOML 与并行任务

Codex Subagent 配置与使用指南：目录、TOML 与并行任务

先说结论

核心概念：Subagent 解决什么问题

什么任务适合，什么任务不适合

自定义 Agent 放在哪里

最小 TOML 怎么写

常用可选配置

继承规则：不写不等于没有

怎样触发 Subagent 工作流

怎样写好一个子任务

控制并发和嵌套深度

一个更稳的实际工作流

第一步：并行调查

第二步：主代理汇总

第三步：单一 Agent 修改

Subagent 与 Skill 的关系

常见问题与解决方案

自定义 Agent 是不是放进去就会自动运行

项目级和用户级应该选哪个

文件名必须和 name 一样吗

多开几个 Agent 一定更快吗

子代理能不能继续创建子代理

怎样避免 Subagent 擅自修改代码

总结

写在最后