OpenAI Codex 的 worktree 功能适合在同一个 Git 仓库里并行跑多个任务，而不影响当前 Local 工作区。提交任务时选择 Worktree，必要时用 Hand off 在 Local 和 Worktree 之间移动线程；Codex 会处理 Git 操作，但同一个 branch 不能同时在两个地方 checkout。

OpenAI Codex Worktree 配置与 Handoff #

OpenAI Codex 的 worktree 功能适合在同一个 Git 仓库里并行跑多个任务，而不影响当前 Local 工作区。提交任务时选择 Worktree，必要时用 Hand off 在 Local 和 Worktree 之间移动线程；Codex 会处理 Git 操作，但同一个 branch 不能同时在两个地方 checkout。

什么是 worktree #

Worktree 只适用于属于 Git repository 的项目，因为它底层使用的是 Git worktrees。你可以把它理解为仓库的第二份 checkout。

每个 worktree 都有自己的一份文件副本，但它们共享同一份 Git 元数据（.git 目录），包括 commits、branches 等信息。这样就能让你并行 checkout 和处理多个 branch。

术语 #

• Local checkout：你创建的仓库。在 Codex app 里有时直接叫 Local。
• Worktree：在 Codex app 里，从你的 local checkout 创建出来的 Git worktree。
• Handoff：在 Local 和 Worktree 之间移动线程的流程。Codex 会处理把工作安全迁移过去所需的 Git 操作。

为什么要用 worktree #

1. 可以和 Codex 并行工作，不影响当前的 Local 环境。
2. 可以把后台任务排队执行，自己继续专注当前前台工作。
3. 之后可以把线程移回 Local，方便检查、测试，或者更直接地协作。

怎么开始使用 worktree #

Worktree 需要 Git repository。先确认你选择的项目本身就在一个 Git 仓库里。

1. 选择 Worktree
   在新建 thread 的界面里，找到 composer 下方的 Worktree。
   你也可以选择一个 local environment，为这个 worktree 运行 setup scripts。

2. 选择起始 branch
   在 composer 下方，选择作为 worktree 起点的 Git branch。这个 branch 可以是 main / master，也可以是功能分支，甚至是带有未提交本地修改的当前 branch。

3. 提交 prompt
   提交任务后，Codex 会基于你选的 branch 创建一个 Git worktree。默认情况下，Codex 在 “detached HEAD” 模式下工作。

4. 选择继续工作的地方
   之后你可以继续直接在 worktree 上工作，也可以把 thread handoff 回 local checkout。无论从 local 到 worktree，还是从 worktree 到 local，thread 和代码都会一起移动，这样你能在另一个 checkout 里继续。

Local 和 Worktree 之间怎么切换 #

Worktree 的外观和你的 local checkout 很像，差别在于它在工作流里的位置。你可以把 Local 当作前台，把 Worktree 当作后台。Handoff 就是把 thread 在两者之间移动的方式。

在底层，Handoff 会处理安全迁移所需的 Git 操作。这里要注意：Git 只允许同一个 branch 同时在一个地方被 checkout。如果某个 branch 已经在 worktree 上 checkout，就不能同时在 local checkout 里再 checkout 一次，反过来也一样。

实际使用中，常见有两条路径：

1. 只在 worktree 上工作。当你能直接在 worktree 上验证改动时，这条路最合适，比如你已经通过 local environment setup script 装好了依赖和工具。
2. 把 thread handoff 到 Local。当你想把 thread 拉到前台时用这条路，比如你想在常用 IDE 里检查改动，或者你的应用一次只能启动一个实例。

只在 worktree 上工作 #

如果你希望一直留在 worktree 上处理改动，可以在 thread 标题栏里点 Create branch here，把 worktree 变成一个 branch。

这样之后，你就可以提交改动、把 branch push 到远端仓库，以及在 GitHub 上创建 pull request。

你也可以通过标题栏里的 Open 按钮在 worktree 中打开 IDE，使用集成终端，或者直接在 worktree 目录里完成其他操作。

记住：如果你在 worktree 上创建了一个 branch，这个 branch 就不能在其他任何 worktree 里 checkout，包括你的 local checkout。

把 thread handoff 到 Local #

如果你想把 thread 拉回前台，在 thread 标题栏里点 Hand off，然后移动到 Local。

这种方式很适合你想在常用 IDE 窗口里查看改动、运行现有开发服务器，或者在你平时使用的同一环境里验证工作结果的时候。

Codex 会处理把 thread 在 worktree 和 local checkout 之间安全移动所需的 Git 步骤。

每个 thread 会始终保留它关联的同一个 worktree。以后如果你再把 thread handoff 回 worktree，Codex 会把它送回同一个后台环境，继续上次的进度。

你也可以反过来操作。若你已经在 Local 里工作，但想把前台腾出来，就用 Hand off 把 thread 移到 worktree。这样 Codex 可以在后台继续跑，你就能回到本地去处理别的事。

由于 Handoff 依赖 Git 操作，.gitignore 里的文件不会随着 thread 一起移动。

高级细节 #

Codex 管理的 worktree 和永久 worktree #

默认情况下，thread 使用的是 Codex-managed worktree。这类 worktree 更轻量，也更像一次性环境。通常一个 Codex-managed worktree 只服务于一个 thread；如果你之后再把这个 thread handoff 回去，Codex 会把它送回同一个 worktree。

如果你想要长期保留的环境，可以在 sidebar 里某个 project 的三点菜单中创建 permanent worktree。这样会把一个新的 permanent worktree 作为独立 project 创建出来。Permanent worktree 不会被自动删除，而且你可以从同一个 worktree 启动多个 thread。

Codex 怎么管理 worktree #

Codex 会把 worktree 创建在 $CODEX_HOME/worktrees。当你启动 thread 时，起始 commit 会是你所选 branch 的 HEAD commit。若你选的 branch 有本地未提交修改，这些未提交改动也会一起应用到 worktree。

这个 worktree 不会被 checkout 成某个 branch，而是保持在 detached HEAD 状态。这样 Codex 就能创建多个 worktree，而不会污染你的 branches。

branch 限制 #

假设 Codex 在 worktree 上完成了一些工作，你又通过 Create branch here 创建了一个 feature/a branch。接着你想在 local checkout 里试用它。如果你去 checkout 这个 branch，就会看到下面的错误：

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

要解决这个问题，你需要在 worktree 上 checkout 另一个 branch，而不是 feature/a。

如果你打算在本地 checkout 这个 branch，应该用 Handoff 把 thread 移到 Local，而不是试图让同一个 branch 同时在两个地方 checkout。

为什么会有这个限制 #

Git 不允许同一个 branch 同时在多个 worktree 里 checkout，因为 branch 代表的是一个可变的单一引用（refs/heads/<name>），其含义就是“某个 working tree 当前被 checkout 的状态”。

当一个 branch 被 checkout 时，Git 会把它的 HEAD 视为该 worktree 的所有权，并要求 commit、reset、rebase、merge 这类操作以明确、串行的方式推进这个引用。如果允许多个 worktree 同时 checkout 同一个 branch，就会出现到底哪个 worktree 的操作更新了 branch reference 的歧义和竞争条件，可能导致丢失 commits、index 不一致，或者冲突处理不清晰。

通过强制“一条 branch 只能对应一个 worktree”，Git 保证每个 branch 都有唯一的权威工作副本，同时仍然允许其他 worktree 通过 detached HEAD 或单独 branch 安全引用同一批 commits。

Worktree 清理 #

Worktree 会占用比较多磁盘空间。每个 worktree 都有自己的一套 repository 文件、依赖、构建缓存等。因此，Codex app 会尽量把 worktree 数量控制在合理范围内。

默认情况下，Codex 会保留最近 15 个 Codex-managed worktree。你可以在 settings 里修改这个上限，或者关闭自动删除，改为自己管理磁盘占用。

Codex 会尽量避免删除仍然重要的 worktree。以下情况不会自动删除 Codex-managed worktree：

• 该 worktree 绑定了 pinned conversation
• thread 还在进行中
• 该 worktree 是 permanent worktree

以下情况会自动删除 Codex-managed worktree：

• 你 archive 了关联的 thread
• Codex 需要删除更旧的 worktree，以满足你配置的数量上限

在删除 Codex-managed worktree 之前，Codex 会先保存该 worktree 上的工作快照。如果你在 worktree 被删除后重新打开 conversation，会看到恢复它的选项。

常见问题 #

我能控制 worktree 创建到哪里吗 #

不能。Codex 会把 worktree 创建在 $CODEX_HOME/worktrees，这样它才能统一管理。

我能在 Local 和 Worktree 之间切换 thread 吗 #

可以。使用 thread 标题栏里的 Hand off，就能在 local checkout 和 worktree 之间移动 thread。Codex 会处理安全迁移所需的 Git 操作。如果你之后再把 thread handoff 回 worktree，Codex 会把它放回之前关联的那个 worktree。

worktree 被删除后，thread 会怎样 #

即使底层的 worktree 目录被删了，thread 仍然可以留在你的历史记录里。对于 Codex-managed worktree，Codex 会在删除前保存快照，并在你重新打开关联 thread 时提供恢复选项。Permanent worktree 不会在你 archive 其 thread 时被自动删除。