---
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="/zh-Hant/docs/codex/official/01-products/33-app-core">
    理解 App 中 threads、modes、Git、terminal 和 review 的關係。
  </Card>
  <Card title="Automations" href="/zh-Hant/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)
