Codex 子代理（subagents）实战：什么时候用、怎么写提示词、怎么自定义

先看结论

子代理（subagent）工作流是：Codex 并行启动多个专门的代理，各自干一块活，最后把结果汇总到一次回复里。它对高度并行的任务特别有用，比如代码库探索，或者实施一个多步骤的功能计划。要点只有几条：

• 适合读多写少：官方的建议是从探索、测试、分诊、总结这类读多的任务开始；并行写代码要更谨慎，多个代理同时改代码会产生冲突，也会增加协调成本；
• 费 token：每个子代理都做自己的模型和工具调用，所以比同样任务的单代理运行消耗更多 token；
• 要主动说：当前的 Codex 版本默认启用子代理工作流，但只有在你直接要求，或适用的 AGENTS.md 或技能指令要求时，才会委派；
• 权限继承：子代理继承父会话当前的沙箱和审批设置，自定义代理文件改不了这些；
• 自定义代理要窄：官方原话的思路是，每个自定义代理一个清晰的职责、匹配这个职责的工具面、以及防止它跑偏到相邻工作的指令。

内容整理自 OpenAI 官方文档，核验日期 2026-10-23；模型名称和可用性以你的账号为准。

为什么要用：把噪音挪出主线程

即使上下文窗口很大，模型仍有极限。如果把探索笔记、测试日志、堆栈、命令输出这些嘈杂的中间输出都灌进你定义需求、约束和决策的主对话，会话会随着时间变得不那么可靠。官方把它描述为两件事：

• 上下文污染（context pollution）：有用的信息被嘈杂的中间输出埋掉；
• 上下文腐烂（context rot）：对话被不太相关的细节填满后，表现逐渐变差。

子代理的做法是把嘈杂的工作移出主线程：

• 主代理专注于需求、决策和最终产出；
• 子代理并行做探索、测试或日志分析；
• 子代理返回摘要而不是原始的中间输出。

任务能独立并行时也能省时间，还能把大任务拆成有边界的小块。

怎么触发：直接说，并说清三件事

本地的 Codex 客户端（桌面应用、命令行、IDE 扩展）在你直接要求，或适用的 AGENTS.md、技能指令要求时才会委派。官方给的直接说法有 “spawn two agents”“delegate this work in parallel”“use one agent per point”。

官方建议一个好的子代理提示词要说明：怎么拆分工作、Codex 是否要等所有代理完成再继续、最终返回什么摘要或输出。官方示例一：

Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

官方示例二，可以直接在你的项目上试：

I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code

这两个提示词的共同点：拆分维度明确（一个点一个代理）、明确等待（wait for all）、明确产出格式（按类别汇总并带文件引用）。当很多代理在跑时，Codex 会等到所有请求的结果都回来，再返回一个合并的回复。

编者提示：官方也说，ChatGPT 工作模式里可以让 ChatGPT 把独立的工作委派给子代理；在大多数智能级别下需要明确要求委派，只有 Ultra 级别才可能主动委派。本文以本地 Codex 客户端为主。

怎么管理：看线程、引导、停止

• 桌面应用：从主线程里显示的活动打开某个子代理线程，查看它的工作；也可以直接对 Codex 说，引导一个运行中的子代理、停止它，或关闭已完成的子代理线程；
• 命令行：用 /subagents 在活跃的代理线程之间切换并查看进行中的线程；同样可以直接对 Codex 说来引导、停止或关闭；
• IDE 扩展：当后台代理面板可用时，活跃的子代理显示在输入框上方；展开面板可以看状态、停止所有活跃的子代理，或打开某个子代理线程。

命令行里还有一个容易忽略的行为：审批请求可能来自不活跃的代理线程，即使你正看着主线程。审批弹层会显示来源线程的标签，可以按 o 打开那个线程，再决定批准、拒绝或回答。

模型与推理强度：默认继承，需要时再调

官方对本地客户端的规则：

• 如果你没有配置子代理的模型或 model_reasoning_effort，子代理继承父代理的模型和推理强度；
• 如果显式的启动请求或 [agents] 默认值选了一个模型，却没指定推理强度，子代理用该模型的默认推理强度；
• 想按任务平衡智能、速度和价格，可以在提示词里要求具体的模型或推理强度，在 config.toml 里配置 [agents] 默认值，或直接在自定义代理文件里设置 model 和 model_reasoning_effort。

官方举的例子是：快速扫描用 gpt-6-luna，更吃重的推理用更高强度的 gpt-6.1-sol 配置。官方对这两个模型的定位：

• gpt-6.1-sol：要求高的代理从它开始，适合需要规划、工具调用、验证并在较大上下文中持续跟进的模糊多步骤工作；账号或工作区需要有访问权限，否则选你能用的模型；
• gpt-6-luna：适合快速、范围窄、清晰可重复或大批量的代理工作。

推理强度越高，响应越慢、token 用量越大，但对复杂工作可能提升质量。官方的指引大意是：需要追踪复杂逻辑、检查假设或处理边界情况的代理（比如审查者、安全代理）用 high；medium 平衡速度和深度；任务简单、速度优先用 low；xhigh、max、ultra 取决于所选模型是否支持。

模型怎么选，可以再看GPT-6 系列模型选型指南。

权限与沙箱：继承，不能在自定义代理里放宽

官方的规则在这里很明确：

• 子代理继承你当前的沙箱策略；在桌面应用和 IDE 里继承输入框下方选择的权限模式，所以要先给父回合选好权限模式，再让 Codex 委派；
• 命令行里，子代理继承父回合当前的沙箱和审批设置，包括用 /permissions 或 --yolo 做的修改，自定义代理文件替换不了；
• 非交互流程里，或任何无法弹出新审批的运行，需要新审批的动作会失败，Codex 把错误返回给父工作流；
• 沙箱和审批要设在父会话上。自定义代理的指令可以要求代理“不要改文件”，但不会创建一个单独的只读沙箱。

最后一条很重要：写进指令里的 “Do not edit files” 是一个约定，不是技术上的权限隔离。

自定义代理：.codex/agents/*.toml

Codex 自带三个内置代理：

• default：通用的兜底代理；
• worker：偏执行，用于实施和修复；
• explorer：偏读，用于代码库探索。

要定义自己的代理，把独立的 TOML 文件放在 ~/.codex/agents/（个人）或 .codex/agents/（项目级）下，每个文件定义一个代理。自定义代理可以改模型设置和指令，或禁用某些支持的能力；它们继承父代理的权限、提供方和 MCP 服务器，这些在代理文件里改不了。

每个独立的自定义代理文件必须有三个字段：

• name：Codex 启动或引用这个代理时用的名字；
• description：给人看的，说明什么时候该用这个代理；
• developer_instructions：定义代理行为的核心指令。

Codex 用 name 字段识别代理。文件名与代理名一致是最简单的约定，但以 name 字段为准。如果自定义代理的名字与内置代理（如 explorer）重名，你的自定义代理优先。

可选字段包括 model、model_reasoning_effort、model_reasoning_summary、model_verbosity。要收窄代理的能力，可以把受支持的功能键设为 false：features.shell_tool、features.apps、features.plugins、features.memories、features.request_permissions_tool；也可以用 skills.config 禁用单个技能。sandbox_mode、approval_policy、model_provider、mcp_servers 这类会话设置放在代理文件里不会覆盖父配置；要让代理用某个 MCP 服务器，需要在父会话里配置。

全局设置：[agents]

全局的子代理设置在 config.toml 的 [agents] 下：

• agents.enabled：启用或关闭多代理工具，默认 true；
• agents.max_concurrent_threads_per_session：限制同时打开的被启动代理线程数（不含主线程），不设置时 Codex 自己选默认值；旧配置里的 agents.max_threads 仍可作为旧别名；
• agents.default_subagent_model：被启动代理的默认模型；
• agents.default_subagent_reasoning_effort：被启动代理的默认推理强度；
• agents.interrupt_message：代理回合被打断时，是否记录模型可见的消息，默认 true。

显式的启动值会覆盖 agents.default_subagent_model 和 agents.default_subagent_reasoning_effort。

一个官方示例：PR 审查

官方的第一个示例把审查拆给专门的自定义代理：pr_explorer 梳理代码库并收集证据，reviewer 找正确性、安全和测试风险，docs_researcher 通过专用的 MCP 服务器核对框架或 API 文档。下面摘取前两个（编者省略了需要额外 MCP 配置的 docs_researcher）。

项目配置 .codex/config.toml：

[agents]
max_concurrent_threads_per_session = 8

.codex/agents/pr-explorer.toml：

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Stay in exploration mode.
Do not edit files.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"""

.codex/agents/reviewer.toml：

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Review code like an owner.
Do not edit files.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""

对应的提示词：

Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

如果你省略了 docs_researcher，把提示词里的第三项去掉即可。官方还给了第二个示例（前端集成调试：code_mapper、browser_debugger、ui_fixer），思路相同：先读后写，每个代理只管一件事，修复动作放在问题复现之后。

这个例子里的分工值得借鉴：探索者用快而便宜的模型加较高的推理强度，审查者用更强的模型，两者都被要求不改文件。但要记住上一节：这些“不要改文件”只是指令，真正的权限仍由父会话决定。

常见坑

• 以为 Codex 会自动并行：本地客户端只在你要求，或 AGENTS.md、技能指令要求时才委派，不说就是单代理；
• 并行写同一批文件：官方明确提醒并行写入会冲突；需要并行改代码时，可以参考git worktree 并行指南给每个任务独立的工作区；
• 没算 token 账：每个子代理都有自己的模型和工具调用，成本比单代理高，别把它当默认选项；
• 在代理文件里写权限：sandbox_mode、approval_policy、mcp_servers 放在代理文件里不会覆盖父配置，要在父会话设置；
• 把“不要改文件”当成只读沙箱：它只是指令，不是权限隔离；
• 提示词没说等不等：官方建议在提示词里说明是否要等所有代理完成再继续，以及返回什么摘要，不说清就别指望得到你想要的汇总格式；
• 代理太泛：一个什么都管的代理等于没拆，每个只给一个清晰职责。

自查清单

• 这个任务是读多写少、能拆成独立块的吗？不是就别用子代理。
• 提示词有没有说清：怎么拆、要不要等、返回什么？
• 父回合的权限模式选对了吗？（子代理继承它。）
• 需要并行写代码时，有没有用 worktree 把工作区隔开？
• 自定义代理是否每个只管一件事？name、description、developer_instructions 三个必填字段是否齐全？
• 需要 MCP 服务器的代理，MCP 是不是配在父会话里？
• 有没有用 agents.max_concurrent_threads_per_session 给并发数设上限？

下一步读什么

• 用 git worktree 并行跑多个 Codex 任务：并行写代码时怎么隔离工作区
• 用 Codex 做代码审查：本地 /review 与 GitHub 审查，和本文的并行审查互补
• AGENTS.md 怎么写才有用：在项目指令里写明什么情况下要用子代理

官方来源

• Subagents：子代理的触发、管理、权限继承与自定义代理字段
• Models：模型与推理强度说明
• Config reference：model、model_reasoning_effort 等字段的可选值
• Sandboxing：沙箱与审批设置

核验日期：2026-10-23。