---
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="/zh-Hant/docs/codex/understanding/skills-subagents-hooks">
    區分流程複用和任務拆分。
  </Card>
  <Card title="Team production" href="/zh-Hant/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)
