如果你已经在用 Codex app 做代码修改、排障或自动化，那么 Worktree 几乎是迟早会碰到的一个概念。它的价值不在于“又多了一个 Git 名词”，而在于让 Codex 能在同一个项目里并行干活，同时尽量不打乱你当前本地 checkout。
这篇文章基于 OpenAI 官方文档整理，重点回答 4 个问题：worktree 到底是什么、为什么 Codex 需要它、Local 和 Worktree 怎么切换、以及使用时有哪些限制要提前知道。
Codex Worktrees 是什么
OpenAI 官方文档里提到，Codex app 里的 worktree 底层使用的是 Git worktrees。它本质上是在同一个仓库基础上，再创建一份额外的工作副本。
这个副本有两个关键特征：
- 它有自己独立的文件工作区，可以单独改代码
- 它和原仓库共享
.git元数据，所以仍然属于同一个 Git 仓库体系
这意味着你可以在一个项目里，同时保留自己的本地开发现场，再让 Codex 在另一个独立副本里继续工作。
OpenAI 也明确写到：在 Git 仓库里，Codex 的 automations 会运行在专门的后台 worktree 上，以避免和你当前正在做的事情发生冲突。
先理解 3 个术语
官方文档里有 3 个词最好先记住：
Local checkout：你自己创建并正在使用的本地项目目录Worktree：Codex 从这个本地项目衍生出来的额外工作副本Handoff：把线程从 Local 移到 Worktree，或者再从 Worktree 移回 Local 的过程
如果只记一句话：Local 更像前台，Worktree 更像后台，Handoff 就是两者之间的安全切换机制。
为什么要用 Worktree
OpenAI 给出的理由很直接，我把它翻成更接近日常开发的话：
1. 让 Codex 并行工作，不打断你当前环境
你本地可能正开着 IDE、开发服务器、数据库连接和一堆未提交改动。如果 Codex 直接在当前目录里改文件，很容易互相影响。
而 worktree 的作用，就是把 Codex 的动作隔离出去。
2. 让后台任务和前台任务分开
如果你希望 Codex 在后台继续做这些事，worktree 很适合：
- 继续追一个复杂排障线程
- 跑自动化巡检
- 处理另一个功能分支上的改动
- 先准备一轮修改，等你空了再看
3. 需要时再把线程带回本地
当你准备认真 review、联调或测试时，可以再把线程 hand off 回 Local，在你熟悉的 IDE 和本地运行环境里继续。
这比一开始就让所有东西都在当前目录里混着跑，要稳很多。
在 Codex app 里怎么开始用
按官方文档的流程，步骤并不复杂：
- 新开线程时，在输入框下方选择
Worktree - 选择要作为起点的分支
- 提交任务，Codex 会基于这个分支创建 worktree
- 后续决定继续留在 worktree，还是 hand off 回 Local
这里有两个细节值得注意。
可以从带本地未提交改动的分支启动
官方文档说明，起始分支可以是：
main/master- 某个 feature branch
- 你当前这个带有未暂存本地改动的分支
这点很实用，说明 worktree 并不只适合“干净仓库”，也适合从你当前工作现场分出一个并行任务。
默认是 detached HEAD
Codex 创建 worktree 后，默认会在 detached HEAD 状态下工作。
这样做的好处是：
- 不会一上来就污染你已有分支
- 可以比较轻量地创建多个 worktree
- 更适合把 worktree 当成一次独立任务环境
如果后面你决定长期保留这部分修改，再在 worktree 里创建 branch 即可。
Local 和 Worktree 之间怎么切换
这部分是我觉得官方文档最有价值的地方，因为它讲的不是“Git 原理”，而是 Codex 里的实际协作方式。
OpenAI 的建议可以概括成两条路径。
路径 1：一直在 Worktree 里完成任务
如果你能直接在 worktree 里验证结果，比如：
- 依赖已经安装好
- 本地环境脚本能正常初始化
- 这个任务不需要占用你当前主开发环境
那最省事的方式就是继续留在 worktree 里。
官方文档提到，这时你可以：
- 在当前 worktree 上创建分支
- 直接提交代码
- 推送到远端仓库
- 在 GitHub 上发起 PR
路径 2：把线程 Hand off 回 Local
如果你想把任务拉回前台，比如：
- 想在日常 IDE 里仔细看 diff
- 需要用你现有的开发服务验证
- 你的应用一次只能跑一个实例
那就适合把线程 hand off 回 Local。
OpenAI 文档特别强调，Handoff 会替你处理底层 Git 操作，让线程和代码一起安全迁移。
而且，每个线程会持续关联同一个 worktree。也就是说，后面如果你再把这个线程移回 Worktree，Codex 会回到原来那份后台环境继续干，而不是重新开一个全新的副本。
适用场景
如果你不确定自己该不该用 worktree，可以先看下面这些高频场景：
- 你正在本地开发，同时想让 Codex 并行处理另一个任务
- 你不希望自动化任务直接碰你当前工作目录
- 你想把 review、排障、重构这类耗时任务放到后台慢慢推进
- 你需要在同一仓库里并行尝试多个方向
一句话概括：只要你担心“Codex 改动会不会影响我当前开发现场”，worktree 基本就是优先选项。
注意事项
这部分建议认真看，因为基本都是容易踩坑的点。
1. 同一个分支不能同时在两个 worktree 里 checkout
官方文档明确说明：Git 不允许同一个分支同时被两个 worktree checkout。
所以如果你已经在某个 worktree 里把改动落到了 feature/a 分支上，那么你不能同时在 Local 里也 checkout 这个分支。否则会碰到类似这样的错误：
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'
正确做法通常有两个：
- 想继续留在后台环境，就让它待在 worktree
- 想切回本地开发，就用 Handoff，而不是强行在两个地方同时 checkout 同一分支
2. .gitignore 里的文件不会跟着 Handoff 走
这点官方文档也点得很明确。由于 Handoff 依赖 Git 操作，凡是被 .gitignore 忽略的文件，都不会自动在线程切换时一起带过去。
这意味着如果你的运行依赖某些本地生成文件、缓存文件或临时配置，切换前要心里有数。
3. Worktree 可能很占磁盘
每个 worktree 都有自己的一套仓库文件、依赖、缓存和构建产物，所以磁盘占用不是小事。
按官方文档，Codex 默认会保留最近 15 个 Codex-managed worktrees，并尝试自动清理更旧的那些。
4. 自动清理不是无脑删除
官方文档提到，以下几类 worktree 通常不会被自动删掉：
- 绑定了 pinned conversation
- 对应线程还在进行中
- 它本身是 permanent worktree
而在自动删除前，Codex 还会先保存一个 snapshot，后续重新打开相关对话时可以恢复。
进阶：Codex-managed worktree 和 permanent worktree 的区别
默认情况下，线程使用的是 Codex-managed worktree。这种 worktree 更偏一次性、轻量级、可回收，通常一条线程对应一份后台副本。
如果你想要一个长期存在的环境，官方文档建议创建 permanent worktree。它不会像临时后台 worktree 那样被自动删除，而且可以从同一个 permanent worktree 开多个线程。
简单理解：
- 临时任务、自动化、并行尝试：优先用 Codex-managed worktree
- 想长期保留一个独立开发副本：考虑 permanent worktree
一句话总结
Codex Worktrees 的核心价值不是“多一个目录”，而是让你把 AI 代理的后台执行和自己的前台开发现场分开。只要你理解了 Local、Worktree、Handoff 和分支限制这几个点，就能更放心地让 Codex 并行推进任务。
参考链接
- OpenAI 官方文档（Codex Worktrees）：https://developers.openai.com/codex/app/worktrees