最后核验：2026-10-23
先看结论
Worktree 的作用，用官方的话说，是让 Codex 在同一个项目里运行多个互相独立的对话而不彼此干扰。每个 worktree 都有一整套自己的仓库文件，但共享同一份提交与分支信息（.git）。几个要点：
- 官方列出的常见错误之一：在同一批文件上同时跑多个实时任务，却没有用 Git worktree。并行的编码对话请各自使用一个 worktree。
- 前提是 Git 仓库：Worktree 底层就是 Git worktree，非 Git 项目用不了。
- 同一个分支只能在一处签出：这是最容易踩的坑，下文有报错原文与解法。
- 新 worktree 不等于现成环境：它只带有已提交到 Git 的文件，依赖、
.env之类要靠安装脚本或.worktreeinclude补齐。 - 有自动清理：默认保留最近 15 个由 Codex 管理的 worktree，详见下文。
本文以 ChatGPT 桌面应用中的 Codex 为准，内容整理自 OpenAI 官方文档，核验日期 2026-10-23；界面与默认值以你当前版本为准。
什么时候该开 Worktree
官方给出的理由有三条：
- 与 Codex 并行工作，又不打乱你当前的本地（Local）环境；
- 把后台任务排队，让你专注在前台的事情上；
- 之后想检查、测试或更直接地协作时，再把对话移回本地。
结合官方的最佳实践，下面这些判断是编者的归纳：
- 同一个项目里要同时推进两件互不相干的事，各开一个对话、各用一个 worktree；
- 想让 Codex 在后台改动，而你本地正在写别的东西，用 worktree 隔离；
- 只是一个很小的改动、而且你想直接在本地 IDE 里看，直接用本地就行，不必为了“用而用”。
另外，官方提到，在 Git 仓库里，定时任务可以在专用的后台 worktree 里运行，不会和你正在进行的工作冲突；非 Git 项目的定时任务则直接在项目目录里运行。
三个术语
- Local（本地检出）：你自己创建的那份仓库，在桌面应用里常简称 Local；
- Worktree：在桌面应用里由你的本地检出创建出来的 Git worktree；
- Handoff（交接）：把一个对话在 Local 与 Worktree 之间移动的流程，Codex 会处理其中需要的 Git 操作，让工作安全地换位置。
官方的比喻是：Local 是前台，Worktree 是后台，Handoff 让对话在两者之间切换。
四步上手
官方的上手步骤如下，先确认你选的项目位于 Git 仓库里：
- 选择 Worktree：在新对话页面，输入框下方选 Worktree。可以选一个本地环境，用来给 worktree 运行安装脚本（见下文）。
- 选择起始分支：在输入框下方选一个分支作为基础，可以是
main/master、某个功能分支，或者带有未暂存本地改动的当前分支。如果选的分支带有本地未提交的改动，Codex 会把这些改动一并应用到 worktree 上。 - 提交提示词：Codex 会基于你选的分支创建一个 Git worktree。默认情况下，它在 detached HEAD（游离 HEAD）状态下工作，不会占用任何分支名，所以可以同时建很多个而不污染你的分支。
- 决定在哪里继续：可以直接留在 worktree 里，也可以把对话交接给本地检出。交接会把对话和代码一起移到另一边。
Codex 管理的 worktree 默认放在 $CODEX_HOME/worktrees。想换位置，可以在 Settings > Worktrees 里改 Worktree root。
两条常见路径
路径一：一直留在 worktree 里
如果你想一直在 worktree 上完成工作，用对话页顶部的 Create branch here 把它变成一个分支，然后就可以提交、推送到远端、在 GitHub 上开 PR。你也可以用顶部的 Open 按钮在 IDE 里打开这个 worktree，或使用集成终端。
这条路适合你能直接在 worktree 里验证改动的情况，例如你已经用本地环境的安装脚本装好了依赖和工具。
路径二：把对话交接给 Local
如果想把对话拉到前台，就在对话页顶部选 Hand off，移到 Local。这适合你想在常用的 IDE 窗口里看改动、跑现有的开发服务器，或者你的应用同一时间只能起一个实例的场合。
几点细节：
- 每个对话会一直对应同一个 worktree；以后再交接回 worktree，Codex 会把它放回同一个后台环境；
- 反方向也可以：如果你正在 Local 里工作、想腾出前台，用 Hand off 把对话移到 worktree，让 Codex 在后台继续；
- 交接用的是 Git 操作，所以被
.gitignore忽略的文件不会随对话移动，除非 Codex 通过.worktreeinclude把它们复制进本地托管的 worktree（见下文）。
最容易踩的坑：同一分支只能在一处签出
Git 只允许一个分支同一时间在一个地方被检出。如果你在 worktree 上用 Create branch here 建了 feature/a，又想在本地检出它，会看到官方文档里这样的报错：
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'
解法有两种：
- 用 Handoff：官方的建议是，如果打算在本地检出这个分支，就用 Handoff 把对话移到 Local，而不是想办法在两边同时检出同一个分支；
- 或者让 worktree 先检出另一个分支，再在本地检出
feature/a。
官方还解释了原因：一个分支代表唯一一个可变引用，Git 把它的 HEAD 视为检出它的 worktree 所有，提交、重置、变基、合并都假定由这一处按顺序推进它。允许多处同时检出同一分支，会带来歧义和竞态，可能丢提交。因此 Git 强制“一个分支一个 worktree”，其他 worktree 仍可通过 detached HEAD 或别的分支引用相同的提交。
让 worktree 里的代码跑起来
官方排错页里有一条专门的“代码在 worktree 上跑不起来”。原因是：worktree 在另一个目录里，默认只继承已经提交到 Git 的文件。依赖、构建产物、.env 这类没进 Git 的东西都不会自动出现。
官方给了两个办法，可以按需组合。
办法一：用本地环境的安装脚本
安装脚本会在 Codex 为新对话创建新 worktree 时自动运行。官方示例是 TypeScript 项目的安装和首次构建：
npm install
npm run build
要点：
- 本地环境只在桌面应用的 Codex 里可用，在应用的设置面板里配置；
- 配置存放在项目根目录的
.codex文件夹里，可以把生成的文件提交到仓库与团队共享； - 如果安装步骤因平台而异，可以为 macOS、Windows、Linux 分别定义脚本覆盖默认值；
- 同一处还能定义“操作（Actions）”，比如启动开发服务器、跑测试，会显示在应用顶栏，在集成终端里运行。
办法二：用 .worktreeinclude 复制被忽略的文件
如果仓库忽略了某些本地文件，而新 worktree 需要它们，就在仓库根目录添加一个 .worktreeinclude，列出要复制的被忽略路径或 .gitignore 风格的模式。官方示例：
# .worktreeinclude
.env
.env.local
config/secrets.json
官方列出的规则：
- 只复制与
.worktreeinclude匹配、且被 Git 忽略的文件，其他未被 Git 跟踪的本地文件不会复制； - 不要列已被 Git 跟踪的文件（它们本来就在 worktree 里）；
- Codex 会自动把被忽略的
AGENTS.override.md复制进本地托管的 worktree，不用你再列； - 会跳过源符号链接，并且不会覆盖新检出里已经存在的文件；
- 这个行为只适用于桌面应用本地托管的 worktree，不适用于远程 worktree，也不适用于你在命令行里自己创建的 Git worktree。
编者提醒：官方示例里列了 .env 和 secrets.json，说明这里复制的可能是敏感文件。这意味着密钥会出现在更多目录里，请只列确实需要的文件，并确保它们始终在 .gitignore 里，不要被提交。
办法三：退回本地验证
官方也提到，你可以把改动签出到常规本地项目里再运行。需要在本地检出同一个分支时，官方的做法是用上文的 Handoff，而不是在两边同时检出。
磁盘与清理规则
每个 worktree 都有自己的一套仓库文件、依赖和构建缓存，会占不少磁盘，所以桌面应用会把数量控制在一个合理范围内。
- 默认保留最近 15 个 Codex 管理的 worktree，可以在设置里改这个上限或关闭自动删除；
- 不会被自动删除的情形：有置顶对话绑定它、对话仍在进行中、它是永久 worktree；
- 会被自动删除的情形：你归档了对应的对话，或 Codex 需要删旧的 worktree 才能满足你设置的上限；
- 删除前会存快照：之后你打开对应对话，会看到恢复它的选项；对话本身仍然留在历史里；
- 永久 worktree：想要一个长期环境，可以在侧边栏某个项目的三点菜单里创建。它会作为独立项目出现，不会被自动删除，也可以在同一个 worktree 上开多个对话；
- 定时任务会产生很多 worktree：官方建议归档不再需要的运行记录，除非你想保留它们的 worktree，否则不要置顶这些运行。
并行不出事的几个习惯
下面前两条出自官方文档，后两条是编者的建议。
- 别让两个对话改同一批文件：每个对话有自己的上下文、消息、结果和目标，可以并行，但改同一批文件时用 worktree 把它们隔开；
- 一个对话对应一个完整结果：官方最佳实践建议一个对话只做一个完整的单元；这样每个 worktree 里的改动也好审查、好合并；
- 开工前就定好各自的范围：并行前先想清楚每个任务动哪些目录、用哪个分支名，减少之后合并时的冲突（编者建议）；
- 改动最终还是要合并回主分支：worktree 只是把并行时的互相覆盖挡在外面，合并时的冲突仍要你来处理（编者提示）。
常见问题
选错了运行目标（Local / Worktree / Cloud）怎么办？ 取消当前这次运行，在输入框里按上方向键，可以找回你上一条提示词。如果是误取消了创建 worktree 而丢了提示词，也是同样的办法。
Worktree 被删了，对话还在吗？ 对话会保留在历史里。Codex 托管的 worktree 在删除前存过快照，重新打开对应对话时可以恢复；永久 worktree 不会因为你归档对话而被自动删除。
能在手机上用吗？ Worktree 不会在手机本地运行。ChatGPT 手机应用控制的是你连接的那台电脑上的 Codex，仓库和 worktree 都留在那台电脑（或它使用的远程开发环境）里。
检查清单
- 项目是 Git 仓库吗？
- 并行的两个任务动的是不同文件吗？如果不是，各开一个 worktree 了吗？
- 新 worktree 的依赖和环境怎么来：安装脚本、
.worktreeinclude，还是退回本地验证？ - 需要在本地检出的分支，是不是已经被某个 worktree 占用了？是的话改用 Handoff。
- 置顶和归档是否合理？定时任务产生的运行有没有及时归档？
下一步读什么
- Codex 新手常见的 8 个错误：并行、权限、规划这些常见坑的整体清单
- Codex 长任务工作流：一个任务要持续很久时怎么设目标和验证
- AGENTS.md 怎么写才有用：被忽略的
AGENTS.override.md会自动复制进本地托管的 worktree - Codex 子代理实战：同一个任务内部的并行，读多写少时更合适
官方来源
- Worktrees：术语、上手步骤、Handoff、
.worktreeinclude、分支限制、清理规则与常见问题 - Local environments：安装脚本与操作的配置
- Troubleshooting：代码在 worktree 上跑不起来、定时任务产生过多 worktree、选错目标后找回提示词
- Best practices：常见错误与“一个对话一个完整结果”
- Long-running work：并行运行目标时用 worktree 隔离
核验日期：2026-10-23。
