Codex App Worktree：隔离改动并行做任务

适用场景

这篇手册适合已经会在 Codex App 中创建普通任务，但还不确定什么时候该选择 Worktree 的用户。

OpenAI 官方文档说明，Worktree 可以让 Codex 在同一个项目中运行多个互不干扰的任务。它适合需要隔离改动、并行试方案、或者希望后台任务不要影响当前本地工作区的场景。

步骤 1：确认项目是 Git 仓库

Worktree 依赖 Git worktree。开始前，先确认项目目录里有 Git 仓库。

你可以在终端运行：

git status

如果命令提示不是 Git 仓库，就不能按 Worktree 流程工作。这个时候可以先初始化仓库，或者继续使用 Local 模式。

步骤 2：新建任务时选择 Worktree

在 Codex App 的新任务输入框下方，选择 Worktree。这一步表示你希望 Codex 不直接改当前本地 checkout，而是在一个隔离环境里处理任务。

适合放到 Worktree 的任务包括：

• 尝试一个新功能。
• 跑一个可能改动范围较大的重构。
• 让 Codex 并行修复多个互不相关的问题。
• 创建一个后台任务，不打断你当前正在编辑的文件。

如果只是让 Codex 解释代码或做很小的文案修改，Local 通常更简单。

步骤 3：选择起始分支并提交任务

Worktree 需要基于一个起始分支创建。你可以选择 main、master、当前功能分支，或其他稳定分支。

提示词建议写清楚隔离意图：

请在 Worktree 中实现这个改动，不要影响我当前 Local 工作区。
完成后总结修改文件、验证命令和是否需要创建分支。

Codex 会在 Worktree 中创建独立 checkout，并在里面执行读取、修改、运行命令等操作。

步骤 4：需要保留成果时创建分支

截图中展示的是在 Worktree 中创建分支的界面。Codex 完成任务后，如果你决定保留这份改动，可以从 Worktree 线程中创建一个分支。

分支名建议保持清楚，例如：

codex/manual-worktree-guide

创建分支后，你可以继续提交、推送，并打开 Pull Request。

步骤 5：需要回到本地时使用 Handoff

如果你希望把 Worktree 里的任务带回 Local，可以使用 Handoff。官方文档把 Handoff 描述为在 Local 和 Worktree 之间移动线程与代码的流程，Codex 会处理底层 Git 操作。

适合 Handoff 到 Local 的情况：

• 你要在自己常用 IDE 中仔细检查改动。
• 项目只能在一个本地开发服务器里验证。
• 你想接手剩余工作，而不是继续让 Codex 在后台处理。

常见错误

不要把同一个分支同时在多个 worktree 中 checkout。Git 本身不允许同一分支被多个 worktree 同时占用。

不要把 Worktree 当成不用审查的安全区。它能隔离改动，但提交前仍然要看 diff、运行测试、确认没有无关文件。

不要把长期环境都放在临时 Worktree 里。如果需要长期维护，可以创建永久 worktree 或单独项目。

小结

Worktree 是 Codex App 里非常适合并行开发的能力。简单任务用 Local，大范围尝试和后台任务用 Worktree；完成后再决定创建分支、提交 PR，或通过 Handoff 带回本地检查。