# Codex 多代理、Subagents 与 Worktrees

> Codex 并行代理、custom agents、Worktrees、Handoff 和后台任务的使用边界,用于把复杂任务拆开而不污染主线程。

URL: https://docs.passion8.cc/docs/codex/subagents-worktrees
Language: zh-CN
Publisher: Passion8

这页补齐 Codex 的并行工作流入口。简单任务继续用单线程;当任务能拆成互不干扰的探索、审查、测试或实现片段时,再让 Codex 开 subagents 或 worktrees。




Subagents 会额外消耗 token,worktrees 会额外占磁盘。不要把强依赖同一批文件的写操作拆给多个代理同时改。




## 能力选择

| 目标 | 推荐能力 | 适合场景 |
| --- | --- | --- |
| 并行阅读和审查 | Subagents | 安全审查、测试缺口、架构风险、日志分析 |
| 后台实现一个独立分支 | Worktree | 你继续在本地工作,Codex 在隔离 checkout 里做实验 |
| 多个长期方向 | Permanent worktree | 重构分支、升级分支、Spike 分支长期保留 |
| 线程在前后台之间切换 | Handoff | 先让 Codex 背景跑,需要人工细看时移回 Local |
| 团队级角色复用 | Custom agents | reviewer、tester、explorer、migration-owner 等固定职责 |

## Subagents

Codex 只有在你明确要求时才会开 subagents。提示词里要写清楚「分几个代理」「每个代理看什么」「是否等待全部完成」「最后返回什么格式」。

```text
用并行 subagents 审查当前分支。
开 3 个代理:
1. 安全和权限风险
2. 测试缺口和回归风险
3. 可维护性和复杂度
等全部完成后,按 P0/P1/P2 汇总,每条带文件路径和理由。
```

适合 subagents 的任务:

| 任务 | 为什么适合 |
| --- | --- |
| 大仓库探索 | 每个代理负责一个目录或领域,减少主线程噪音 |
| PR review | 不同代理分别看安全、正确性、测试 |
| 日志和失败原因分析 | 一个代理看应用日志,一个代理看 CI,一个代理看最近 diff |
| 文档覆盖审计 | 一个代理对照官方文档,一个代理检查本地导航和链接 |

不适合 subagents 的任务:

- 多个代理同时重写同一个核心文件。
- 需求还没定清楚,每个代理都可能朝不同方向发挥。
- 用户只需要一个小修复,并行开销比收益更高。

## Custom agents

Custom agents 是可复用的代理角色。个人级放在 `~/.codex/agents/`,项目级放在 `.codex/agents/`。每个 TOML 文件至少需要:

```toml
name = "reviewer"
description = "Review code for correctness, security, regressions, and missing tests."
developer_instructions = """
Prioritize concrete bugs over style.
Return findings with file paths and severity.
Do not modify files.
"""
model_reasoning_effort = "high"
sandbox_mode = "read-only"
```

常用字段:

| 字段 | 用途 |
| --- | --- |
| `name` | Codex 调用这个 agent 的稳定名称 |
| `description` | 什么时候应该使用它 |
| `developer_instructions` | 这个代理的核心行为和输出要求 |
| `model` | 需要固定模型时再写 |
| `model_reasoning_effort` | 审查、安全、复杂推理建议 `high` |
| `sandbox_mode` | 只读审查代理建议 `read-only` |
| `mcp_servers` | 给某个代理绑定特定 MCP |

全局并发限制在 `config.toml` 的 `[agents]` 里配置:

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

`max_depth` 默认保持 1 更稳,避免代理继续派生代理造成不可控的 fan-out。

## Worktrees

Codex App 的 worktree 基于 Git worktree。它会给后台线程创建独立 checkout,让 Codex 改代码时不干扰你的当前工作区。

使用前提:

- 项目必须是 Git 仓库。
- 当前分支、依赖和环境要能在新 checkout 里复现。
- 被 `.gitignore` 忽略但 worktree 必须用到的文件,需要用 `.worktreeinclude` 明确复制。

`.worktreeinclude` 示例:

```text
.env.local
config/secrets.json
```

只列确实需要复制到 Codex 托管 worktree 的本地文件。不要把 tracked 文件写进去,也不要无脑复制整个密钥目录。

## Handoff

Handoff 用来在线程和代码之间切换前后台:

| 流程 | 说明 |
| --- | --- |
| Local -> Worktree | 你想释放当前工作区,让 Codex 在后台继续 |
| Worktree -> Local | 你想用自己的 IDE、测试环境或 dev server 细看结果 |
| Worktree -> branch | 结果可以独立成分支,准备 commit / push / PR |

Git 不允许同一个分支同时被两个 worktree checkout。Codex 的 Handoff 会处理必要的 Git 操作,比手动 checkout 同一个分支更稳。

## 并行安全策略

把并行工作流当成临时分支治理:

| 事项 | 建议 |
| --- | --- |
| 分支命名 | `codex/<task>` 或 `spike/<task>` |
| 权限 | 探索和 review 用 `read-only`,实现用 `workspace-write` |
| 依赖安装 | 在 worktree 里单独安装,不要污染主 checkout 的锁文件 |
| 验证 | 每个 worktree 合并前必须跑对应测试 |
| 合并 | 先看 diff,再 cherry-pick、merge 或让 Codex 准备 PR |
| 清理 | 归档线程、删除不需要的 worktree,避免依赖缓存膨胀 |

## Passion8 边界

本地 CLI、App 的 Local 线程、IDE 扩展使用本机 `~/.codex` 配置,可以走 Passion8 的 `https://passion8.cc/v1`。

Cloud task、Slack、Linear、GitHub 托管 review 运行在 OpenAI 官方云端环境,不要假设它们继承本机 Passion8 Provider。需要云端能力时,按官方 ChatGPT / Codex workspace 的连接和权限配置处理。

## 接着看



- [代码管理:Git 与 GitHub](https://docs.passion8.cc/docs/codex/git): 理解 branch、commit、worktree 和回滚。
- [Review、GitHub 与 PR 工作流](https://docs.passion8.cc/docs/codex/review-github): 本地 /review、GitHub PR review 和 CI review。
- [权限、沙箱与安全](https://docs.passion8.cc/docs/codex/permissions-sandboxing): 给并行代理设置更窄的权限边界。



## 官方参考

- [Codex manual: Subagents](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Worktrees](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: CLI features](https://developers.openai.com/codex/codex-manual.md)