---
title: "用 Subagents 拆分任务"
description: "判断什么时候该用 Codex subagents 并行拆任务，什么时候保持单 agent，并控制上下文、权限和成本。"
verifiedAt: "2026-05-07"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Subagents 用来把复杂任务拆给多个专门 agent 并行处理，再由主 agent 汇总结果。它适合高度并行的探索、审查和事实核验，不适合小任务或强串行任务。

> [!WARNING]
> Subagents 不是越多越强。每个 subagent 都会消耗模型和工具资源，也会增加上下文、审批和写入冲突成本。

当前 Codex releases 默认启用 subagent workflows，但 Codex 只会在你明确要求时 spawn subagents。官方文档也强调：每个 subagent 都会独立做模型和工具工作，因此会比单 agent 消耗更多 tokens。

<Cards>
  <Card title="Subagents" href="https://developers.openai.com/codex/subagents">
    查看官方 subagents 配置和使用说明。
  </Card>
  <Card title="Skills vs Subagents" href="/docs/codex/understanding/skills-subagents-hooks">
    区分流程复用和任务拆分。
  </Card>
  <Card title="Team production" href="/docs/codex/understanding/team-production">
    多 agent 进入团队流程前先明确边界和治理。
  </Card>
</Cards>

## 什么时候该拆

```mermaid
flowchart TD
    Task["任务来了"]
    Independent{"子问题是否独立?"}
    Outputs{"输出是否能汇总?"}
    Write{"是否会写同一批文件?"}
    Use["适合 subagents"]
    Single["保持单 agent"]

    Task --> Independent
    Independent -->|否| Single
    Independent -->|是| Outputs
    Outputs -->|否| Single
    Outputs -->|是| Write
    Write -->|会冲突| Single
    Write -->|不会| Use
```

适合拆：

- PR 同时做安全、测试、文档和架构审查。
- 大型代码库探索多个模块。
- 一个 agent 查官方文档，另一个读代码。
- 多个只读维度可以并行。

不适合拆：

- 单文件修改。
- 小 bug。
- 强依赖同一段上下文的调试。
- 多个 worker 会改同一文件。
- non-interactive 环境无法处理审批。

## 内置角色怎么用

Codex 内置三类 agents：

| agent | 用途 | 推荐边界 |
| --- | --- | --- |
| `explorer` | read-heavy codebase exploration | 只读查证、回答具体代码库问题。 |
| `worker` | implementation and fixes | 执行明确修改，必须有文件 ownership。 |
| `default` | general-purpose fallback | 无特定角色时兜底。 |

新手建议先用只读 explorer。需要写文件时，只给一个 worker 明确写入范围。不要让多个 worker 同时改同一批文件。

CLI 中可以用 `/agent` 切换 active agent thread，查看或继续某个 subagent 的上下文。任务结束后，让主 agent close completed agent threads，避免后台线程长期占用上下文和状态。

## 写给 subagent 的任务要窄

好的 subagent 任务应该包含：

- 它负责什么。
- 它不能碰什么。
- 输入范围。
- 输出格式。
- 是否只读。
- 是否允许调用外部工具。

示例：

```text
只读检查 PR diff 中的权限和数据泄露风险。
不要修改文件。
输出按严重程度排序的 findings，每条包含文件、证据和建议。
```

任务越窄，主 agent 越容易汇总。

## 权限和审批

Subagents 的权限边界不能忽略：

- 它们可能继承当前 sandbox。
- 它们可能触发自己的审批请求。
- 它们可能读取不同上下文。
- 它们可能产生写入冲突。

建议：

- 初期全部只读。
- 写入任务只交给一个 worker。
- 明确文件 ownership。
- 非交互任务避免需要审批的 subagent 动作。
- 结束后汇总每个 subagent 做了什么。

官方行为要记住两点：

- Subagents inherit 当前 sandbox policy。
- 交互式 CLI 中，inactive thread 也可能弹出 approval request；approval overlay 会显示来源 thread。

非交互流程中，如果某个动作需要新的 approval 但无法弹窗，该动作会失败并把错误返回给 parent workflow。因此 CI、批处理、自动化里更适合只读 subagents 或预先收窄权限边界。

## 自定义 agents

当内置角色不够用时，可以添加 custom agent：

```text
~/.codex/agents/reviewer.toml
.codex/agents/reviewer.toml
```

每个 standalone TOML 文件定义一个 agent，至少包含：

```toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""
```

可以额外设置 `model`、`model_reasoning_effort`、`sandbox_mode`、`mcp_servers`、`skills.config` 等配置。全局并发和深度放在 `[agents]`：

```toml
[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800
```

默认 `agents.max_threads` 是 6，`agents.max_depth` 是 1。不要轻易提高 depth，递归拆分会快速增加成本、等待时间和不可预测性。

## 常见坑

- 为了并行而并行。
- 子任务没有明确交付物。
- 多个 worker 改同一文件。
- 子结果都是自然语言，无法汇总。
- 没有说明哪个结果是事实、哪个是推断。
- 忘记 token 和工具调用成本。
- 让 subagent 继续无限拆分。

Subagents 的价值来自清晰分工，而不是数量。

## 验收标准

使用 subagents 后，应能回答：

- 每个 subagent 负责什么。
- 哪些只读，哪些可写。
- 输出如何进入主结论。
- 是否真的更快或更全面。
- 是否产生冲突或重复判断。
- 成本是否值得。

不能回答这些问题，就回到单 agent。

## 官方资料

- [Subagents](https://developers.openai.com/codex/subagents)
- [Subagent concepts](https://developers.openai.com/codex/concepts/subagents)
- [Configuration reference](https://developers.openai.com/codex/config-reference)
- [Slash commands in Codex CLI](https://developers.openai.com/codex/cli/slash-commands)
