# Codex 子代理实战：会拆任务，才值得并行

> 从任务边界、调用方式、权限继承到结果验收，说明如何在 Codex App、CLI 与 IDE 中安全使用 subagents，并避开并行写入、上下文污染和成本失控。

- Source: https://www.aifreeapi.com/zh/posts/codex-subagents
- Language: zh
- Published: 2026-08-16
- Updated: 2026-08-16
- Publisher: AI Free API (https://www.aifreeapi.com)

Codex 的 subagent 最适合解决两类问题：一类是任务确实能独立推进，另一类是中间过程很吵，却不该挤占主线程。代码库探索、测试分诊、日志归纳和多维审查都可能符合这两个条件；同一个文件上的连续实现、需要频繁共同决策的架构设计，通常不符合。

这项功能在当前本地 Codex 版本中默认可用。你可以直接要求 Codex 委派独立工作，项目中的 `AGENTS.md` 或适用 skill 也可以明确要求使用子代理。它不是免费的并发：每个子代理都会进行自己的模型推理和工具调用，因此总 token 消耗通常高于可比的单代理执行。OpenAI 在[官方 Subagents 文档](https://learn.chatgpt.com/docs/agent-configuration/subagents)中给出的起点也很克制——先从读取为主的探索、测试、分诊和摘要开始，谨慎处理并行写入。

## 先判断任务能不能真正分开

一个可委派的子任务应该能在较少追问的情况下独立完成，并把结果压缩成主线程可判断的输入。可以用四个问题筛选：

1. 它是否有自己的输入、边界和完成条件？
2. 它是否不依赖另一个子任务尚未做出的决定？
3. 如果需要写文件，修改范围是否与其他代理明确错开？
4. 主线程是否知道收到什么证据后才能继续？

| 工作 | 适合并行的原因 | 需要留在主线程的决定 |
|---|---|---|
| 分别检查安全、测试缺口和可维护性 | 评价视角独立，主要是读取 | 哪些发现成立、优先级如何 |
| 按模块定位同一错误的调用路径 | 搜索区域可拆分 | 根因判断与修复方案 |
| 同时修改共享类型和多个调用方 | 文件与接口互相依赖 | 通常先确定接口，再顺序修改 |
| 运行不同测试组并归纳失败 | 执行互不阻塞 | 区分真实回归、环境问题和偶发失败 |

如果你无法为每个分支写出不同的完成条件，就不要用代理数量代替任务分析。那只会把同一个模糊问题复制多次。

![判断任务是否适合交给多个 Codex 子代理的边界图](https://www.aifreeapi.com/posts/zh/codex-subagents/img/delegation-boundary.webp)

## 提示词要定义分工，也要定义回传

“帮我并行处理”给出的自由度太大。更可靠的请求会说明代理数量、每个代理的责任、是否允许写入、主线程何时继续，以及最终需要什么形式的摘要。例如：

```text
请用三个子代理审查当前分支与 main 的差异：
- explorer 只读追踪受影响的执行路径；
- reviewer 检查正确性、安全风险和缺失测试；
- 第三个代理只运行相关测试并归纳失败，不修改文件。

等待三个代理全部返回。每个结果都给出文件位置、证据、影响和不确定项。
最后由主线程去重，区分已证实问题与建议，不要自动修改代码。
```

这段请求的关键不在角色名字，而在责任不重叠、默认只读、证据格式一致，并且把最终判断留给主线程。若任务需要实现，可以在问题已经定位后，再单独给一个 worker 明确的文件范围和验证命令，而不是让探索代理边找边改。

## 子线程继承的权限不会自动变安全

本地 Codex 的子代理继承当前 sandbox 或权限模式。在 App 和 IDE 中，应在委派前确认输入框下方选择的权限；在交互式 CLI 中，来自非当前 agent thread 的审批请求也可能弹出，界面会标出来源，按 `o` 可以打开对应线程再决定是否批准。无法显示新审批的非交互执行遇到受限动作时会失败，并把错误返回父工作流。

这意味着“交给子代理”不是权限隔离的同义词。更稳妥的做法是：

- 探索、文档核验和审查使用只读边界；
- 实现代理只拥有完成目标所需的最小写入范围；
- 不把多个代理指向同一组文件；
- 对安装软件、外部写入、凭据或网络动作保留明确审批；
- 在启动前确认父线程的实时权限选择，因为生成子代理时会重新应用这些选择。

![Codex 主线程、子代理权限继承、审批与结果回传的控制闭环](https://www.aifreeapi.com/posts/zh/codex-subagents/img/permission-loop.webp)

## 在不同客户端里观察和纠偏

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`。

```toml
name = "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 安全配置指南](/zh/posts/codex-config-toml)；不要为了启用一个已默认可用的功能复制整份配置文件。

## 汇总不是验收

主线程收到多个摘要后，至少要做三件事：把重复发现合并；把“观察到的事实”“推断”和“建议”分开；对高影响结论回到文件、命令输出或官方资料复核。测试代理说“通过”时，要确认它运行了什么；审查代理指出漏洞时，要确认执行路径是否可达；探索代理没有找到引用时，要检查它的搜索范围。

一个健康的 subagent 工作流结束时，主线程应该比开始时更干净，而不是只多出几个完成标记。它保留需求、关键决定和最终责任；子代理承担有边界的噪声工作；证据经过汇总和复核后，才成为可以继续实现或交付的依据。

如果你真正要决定的是使用 Codex 还是另一种本地编码工具，而不是如何委派，可以转到 [Claude Code 与 Codex 的工作流对比](/zh/posts/claude-code-vs-codex)。