---
title: "用 Worktrees 并行开发"
description: "理解 Codex App 中 worktree 的用途：隔离并行任务、保护当前工作树，并安全地 handoff 回本地。"
verifiedAt: "2026-05-07"
---

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

Worktree 让 Codex 可以在同一个 Git repository 中为不同任务创建隔离 checkout。它适合并行任务、后台任务和实验性改动，核心价值是减少对当前 Local checkout 的干扰。

> [!TIP]
> 当你或其他 agent 正在修改当前工作树时，优先考虑 worktree 或更窄文件边界。不要让多个任务直接挤在同一个 checkout 里。

<Cards>
  <Card title="Worktrees" href="https://developers.openai.com/codex/app/worktrees">
    查看 Codex App worktree 的官方说明。
  </Card>
  <Card title="App core" href="/docs/codex/official/01-products/33-app-core">
    理解 App 中 threads、modes、Git、terminal 和 review 的关系。
  </Card>
  <Card title="Automations" href="/docs/codex/official/01-products/35-app-automation">
    了解 automations 如何使用后台 worktrees。
  </Card>
</Cards>

## 为什么需要 worktree

```mermaid
flowchart LR
    Local["Local checkout<br/>你的当前工作"] --> Risk["直接并行修改会冲突"]
    WorktreeA["Worktree A<br/>任务 1"] --> Review["独立审查"]
    WorktreeB["Worktree B<br/>任务 2"] --> Review
    Risk --> WorktreeA
    Risk --> WorktreeB
```

适合：

- 同一 repo 中并行跑多个 Codex thread。
- 让后台任务不影响当前 IDE 和 dev server。
- 试一个方案但不想污染本地工作树。
- 等 Codex 完成后再决定是否 handoff 回 Local。

不适合：

- 非 Git 项目。
- 只改一个小文件的简单任务。
- 你不熟悉 Git worktree 和 branch 限制。

## Local、Worktree、Handoff

Local：

- 你当前日常使用的 checkout。
- 适合前台开发、IDE、已有 dev server。

Worktree：

- 同一 repo 的另一份 checkout。
- 有自己的文件副本。
- 与 repo 共享 Git metadata。
- 适合隔离任务。

Handoff：

- 在 Local 和 Worktree 之间移动 thread 和代码。
- 适合把后台任务带回前台审查或继续开发。

不要手动在多个 worktree 中同时 checkout 同一个 branch。Git 会阻止这种情况，以避免同一个 branch 被多个 working tree 同时修改。

## 基本流程

1. 在 App 中创建新 thread。
2. 选择 Worktree mode。
3. 选择起始 branch。
4. 提交任务 prompt。
5. Codex 在隔离 worktree 中工作。
6. 在 App 中审查 diff。
7. 选择继续在 worktree 上创建 branch，或 handoff 回 Local。

任务 prompt 仍要写清：

- 目标。
- 文件范围。
- 禁止事项。
- 验证命令。
- 是否允许新增依赖。

Worktree 只隔离文件，不替你定义任务边界。

官方流程里，Worktree mode 会让 Codex 基于你选择的 starting branch 创建 Git worktree。默认情况下，Codex 使用 detached HEAD，这样可以创建多个 worktree 而不污染本地 branches。需要长期保留时，再在 worktree 上创建 branch。

## 什么时候留在 worktree

留在 worktree 适合：

- 任务可以独立验证。
- 依赖和环境在 worktree 中可用。
- 准备直接从 worktree 创建 branch 和 PR。
- 不需要你当前 Local 的特殊状态。

检查：

- 测试能否在 worktree 中运行。
- dev server 是否能独立启动。
- 是否有未提交依赖或环境文件缺失。

## 什么时候 handoff 回 Local

Handoff 回 Local 适合：

- 你想用常用 IDE 审查。
- 只能运行一个本地服务实例。
- 任务需要你当前 Local 的未提交上下文。
- 要继续人工开发。

Handoff 前先确认：

- Local 工作树是否干净或已保存。
- 是否会覆盖当前未提交改动。
- `.gitignore` 文件是否需要额外处理。
- 目标 branch 是否已被其他 worktree checkout。

Handoff 会移动 thread 和代码。Codex 会处理必要的 Git 操作，因为 Git 不允许同一个 branch 同时 checkout 在多个 worktree 中。

如果你在 worktree 上创建了 `feature/a` branch，再试图在 Local checkout 同一个 branch，Git 会报错：

```text
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'
```

这种情况下，不要强行改 Git metadata。要么把 worktree 切到别的 branch，要么用 Handoff 把 thread 和改动带回 Local。

## Codex-managed 和 permanent worktrees

Codex-managed worktree：

- 默认由 Codex 为单个 thread 创建。
- 更轻量，适合一次性任务。
- thread handoff 回 worktree 时会回到同一个关联 worktree。
- 会受自动清理策略影响。

Permanent worktree：

- 从 project sidebar 的 three-dot menu 创建。
- 会成为长期 project。
- 不会因为普通 thread archive 自动删除。
- 适合长期分支、长期环境或固定实验线。

不要把 permanent worktree 当作随手创建的草稿目录。它会占用磁盘和认知负担。

## 自动清理和磁盘空间

Worktree 会占磁盘空间，尤其当项目有依赖、build cache 或大型生成物时。

建议：

- 定期清理不再需要的 Codex-managed worktrees。
- Permanent worktree 只用于长期环境。
- 不把 worktree 当备份。
- 重要改动及时创建 branch 或 PR。

自动清理前，仍要确认是否有未保存的重要工作。

官方文档说明：Codex 默认保留最近 15 个 Codex-managed worktrees。你可以在 settings 里调整上限或关闭自动删除。

Codex-managed worktree 不会自动删除的情况包括：

- conversation 被 pinned。
- thread 仍在进行。
- worktree 是 permanent worktree。

会自动删除的情况包括：

- associated thread 被 archive。
- 需要删除旧 worktrees 以保持数量限制。

删除前 Codex 会保存 snapshot。如果你重新打开对应 conversation，可以看到恢复选项。

## local environment 配合

worktree 是另一份 checkout，只包含 Git 跟踪文件。依赖、生成文件、未提交配置、本地缓存通常不会自动出现。

因此，worktree 任务应配合 local environment：

1. 在 `.codex` 中配置 setup script。
2. 创建 worktree 时自动安装依赖或初始化。
3. 用 actions 启动 dev server、build、test。
4. 让 Codex 在 worktree terminal 中验证。

如果没有 setup script，很多“worktree 跑不起来”的问题其实不是代码问题，而是环境没有初始化。

## 并行边界

Worktree 适合并行，但仍要定义边界：

| 场景 | 建议 |
| --- | --- |
| 两个任务改不同模块 | 可以分别开 worktree |
| 两个任务都改同一个核心文件 | 不建议并行 |
| 一个任务只读分析，一个任务写代码 | 只读任务不一定需要 worktree |
| 后台 automation | Git repo 中默认适合 dedicated worktree |
| 当前 Local 有未提交关键改动 | 先保存或明确是否带入 starting branch |

## 安全检查清单

使用 worktree 前确认：

- 项目是 Git repository。
- 当前 Local dirty files 已知。
- 任务范围不会和其他 agent 冲突。
- 验证命令能在 worktree 中运行。
- 不依赖 Local 中未提交但未带入的文件。
- Handoff 前已看过 diff。

Worktree 的目的不是让并行更多，而是让并行可控。

## 官方资料

- [Worktrees](https://developers.openai.com/codex/app/worktrees)
- [Local environments](https://developers.openai.com/codex/app/local-environments)
- [Codex app features](https://developers.openai.com/codex/app/features)
- [Git worktree](https://git-scm.com/docs/git-worktree)
