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：

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

一个自定义 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 = """
你只负责审查，不修改代码。
优先报告能够复现或能从代码路径证明的问题。
每个问题都要给出文件位置、影响和建议验证方法。
如果没有发现实质问题，明确说明未发现，而不是凑数量。
"""

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

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

常见字段包括：

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. 输出：需要结论、证据、文件位置还是测试结果。
5. 完成条件：什么时候可以停止并返回主代理。

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

1
2
3
4

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

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

控制并发和嵌套深度

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

1
2
3

[agents]
max_threads = 6
max_depth = 1

主要配置包括：

根会话深度是 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 可以被配置为使用某些 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