Codex 的 subagent 最适合解决两类问题：一类是任务确实能独立推进，另一类是中间过程很吵，却不该挤占主线程。代码库探索、测试分诊、日志归纳和多维审查都可能符合这两个条件；同一个文件上的连续实现、需要频繁共同决策的架构设计，通常不符合。
这项功能在当前本地 Codex 版本中默认可用。你可以直接要求 Codex 委派独立工作，项目中的 AGENTS.md 或适用 skill 也可以明确要求使用子代理。它不是免费的并发：每个子代理都会进行自己的模型推理和工具调用，因此总 token 消耗通常高于可比的单代理执行。OpenAI 在官方 Subagents 文档中给出的起点也很克制——先从读取为主的探索、测试、分诊和摘要开始，谨慎处理并行写入。
先判断任务能不能真正分开
一个可委派的子任务应该能在较少追问的情况下独立完成，并把结果压缩成主线程可判断的输入。可以用四个问题筛选：
- 它是否有自己的输入、边界和完成条件？
- 它是否不依赖另一个子任务尚未做出的决定？
- 如果需要写文件，修改范围是否与其他代理明确错开？
- 主线程是否知道收到什么证据后才能继续？
| 工作 | 适合并行的原因 | 需要留在主线程的决定 |
|---|---|---|
| 分别检查安全、测试缺口和可维护性 | 评价视角独立，主要是读取 | 哪些发现成立、优先级如何 |
| 按模块定位同一错误的调用路径 | 搜索区域可拆分 | 根因判断与修复方案 |
| 同时修改共享类型和多个调用方 | 文件与接口互相依赖 | 通常先确定接口，再顺序修改 |
| 运行不同测试组并归纳失败 | 执行互不阻塞 | 区分真实回归、环境问题和偶发失败 |
如果你无法为每个分支写出不同的完成条件，就不要用代理数量代替任务分析。那只会把同一个模糊问题复制多次。
提示词要定义分工，也要定义回传
“帮我并行处理”给出的自由度太大。更可靠的请求会说明代理数量、每个代理的责任、是否允许写入、主线程何时继续，以及最终需要什么形式的摘要。例如：
text请用三个子代理审查当前分支与 main 的差异： - explorer 只读追踪受影响的执行路径； - reviewer 检查正确性、安全风险和缺失测试； - 第三个代理只运行相关测试并归纳失败，不修改文件。 等待三个代理全部返回。每个结果都给出文件位置、证据、影响和不确定项。 最后由主线程去重，区分已证实问题与建议，不要自动修改代码。
这段请求的关键不在角色名字，而在责任不重叠、默认只读、证据格式一致，并且把最终判断留给主线程。若任务需要实现，可以在问题已经定位后，再单独给一个 worker 明确的文件范围和验证命令，而不是让探索代理边找边改。
子线程继承的权限不会自动变安全
本地 Codex 的子代理继承当前 sandbox 或权限模式。在 App 和 IDE 中，应在委派前确认输入框下方选择的权限；在交互式 CLI 中，来自非当前 agent thread 的审批请求也可能弹出，界面会标出来源，按 o 可以打开对应线程再决定是否批准。无法显示新审批的非交互执行遇到受限动作时会失败，并把错误返回父工作流。
这意味着“交给子代理”不是权限隔离的同义词。更稳妥的做法是：
- 探索、文档核验和审查使用只读边界；
- 实现代理只拥有完成目标所需的最小写入范围；
- 不把多个代理指向同一组文件；
- 对安装软件、外部写入、凭据或网络动作保留明确审批；
- 在启动前确认父线程的实时权限选择，因为生成子代理时会重新应用这些选择。
在不同客户端里观察和纠偏
Codex 负责启动、等待、转发后续指令和汇总结果，但你仍应观察代理是否在做被委派的事情。
- Codex App：从主线程显示的活动打开子线程；也可以直接要求 Codex 引导、停止或关闭某个线程。
- Codex CLI：使用
/agent在 agent threads 之间切换，查看进行中的工作；审批弹层会告诉你请求来自哪个线程。 - IDE 扩展：有 background-agent 面板时，可以展开查看状态、停止活动代理或进入某个子线程。
如果一个代理开始修改不属于它的文件，不要等待最终摘要再处理。直接停止或重定向它，同时检查其他代理是否以它的输出为前提。并行工作中最贵的错误通常不是一次失败，而是多个分支基于错误假设继续前进。
需要长期复用时，再定义 custom agent
Codex 自带 default、worker 和 explorer。只有当同一种责任会重复出现，而且模型、推理强度、sandbox 或工具边界确实需要固定时，才值得创建 custom agent。个人配置放在 ~/.codex/agents/，项目配置放在 .codex/agents/；每个 TOML 文件至少需要 name、description 和 developer_instructions。
tomlname = "dependency_auditor" description = "只读检查依赖升级带来的 API 与安全风险。" model = "gpt-5.6-terra" model_reasoning_effort = "high" sandbox_mode = "read-only" developer_instructions = """ 追踪实际使用路径，核对破坏性变更与安全公告。 返回文件位置、直接来源、不确定项和需要主线程确认的决定。 不要修改仓库文件。 """
模型选择也应服务于责任，而不是地位：官方当前建议用 gpt-5.6 处理高难度、多步骤判断，用 gpt-5.6-terra 做更快的读取密集型支持任务，用 gpt-5.6-luna 处理范围清楚、可重复的窄任务。具体可用模型取决于账户、认证方式和客户端，保存配置前应回看当前文档。
全局并发与默认模型等设置位于 [agents] 下。若你还需要理解用户级、项目级和临时覆盖的优先级，再查看Codex config.toml 安全配置指南；不要为了启用一个已默认可用的功能复制整份配置文件。
汇总不是验收
主线程收到多个摘要后，至少要做三件事：把重复发现合并；把“观察到的事实”“推断”和“建议”分开；对高影响结论回到文件、命令输出或官方资料复核。测试代理说“通过”时，要确认它运行了什么；审查代理指出漏洞时，要确认执行路径是否可达；探索代理没有找到引用时，要检查它的搜索范围。
一个健康的 subagent 工作流结束时，主线程应该比开始时更干净，而不是只多出几个完成标记。它保留需求、关键决定和最终责任；子代理承担有边界的噪声工作；证据经过汇总和复核后，才成为可以继续实现或交付的依据。
如果你真正要决定的是使用 Codex 还是另一种本地编码工具，而不是如何委派，可以转到 Claude Code 与 Codex 的工作流对比。
