在使用 Codex App 做代码任务时，一个很实用的功能是 Worktree，工作树。

简单理解，工作树就是给当前 Git 仓库创建一个独立的“副本工作区”。Codex 可以在这个副本里改代码、跑任务、做实验，而不影响你本地正在编辑的代码。

工作树是什么？

Codex 的工作树基于 Git worktree 实现。

它不是简单复制一份项目，而是在同一个 Git 仓库基础上创建另一个 checkout。每个工作树都有自己的一份文件，但共享同一套 Git 元数据，比如提交、分支等。

这样做的好处是：
你可以在本地继续开发当前功能，同时让 Codex 在另一个工作树里处理别的任务。

可以把它理解为：

Local：你当前正在使用的主工作区
Worktree：Codex 用来独立执行任务的后台工作区

为什么需要工作树？

如果直接让 Codex 在本地项目里改代码，可能会遇到几个问题：

• 你正在改的文件被 Codex 同时修改
• 还没完成的本地改动和 Codex 的改动混在一起
• 多个任务同时进行时，diff 变得很难 review
• 自动化任务可能影响你当前开发环境

工作树的价值就是隔离。

Codex 在工作树里干活，你在 Local 里继续开发。等 Codex 完成后，你再决定是否查看、接手、合并或丢弃这部分改动。

怎么使用 Codex 工作树？

使用前有一个前提：项目必须是 Git 仓库。非 Git 项目无法使用工作树隔离。

基本流程如下：

1. 在 Codex App 中新建线程
2. 在输入框下方选择 Worktree
3. 选择基于哪个分支创建工作树，比如 main、master 或当前 feature 分支
4. 输入任务，让 Codex 开始执行
5. 等任务完成后，选择继续在工作树里处理，或者 handoff 回 Local

Codex 默认会基于你选择的分支创建一个独立工作树，然后在里面执行任务。

Handoff 是什么？

Handoff 可以理解为“把任务在线程和工作区之间转交”。

比如 Codex 已经在工作树里完成了一些修改，你想用自己熟悉的 IDE 检查代码、运行项目、调试页面，就可以把这个线程 handoff 到 Local。

反过来也可以。
如果你一开始在 Local 里让 Codex 处理任务，后来想把它放到后台继续跑，也可以 handoff 到 Worktree。

这个功能的意义是：
你不用手动处理复杂的 Git 操作，Codex 会帮你安全地把线程和代码迁移到合适的工作区。

适合使用工作树的场景

工作树最适合这些情况：

1. 并行开发

你正在开发 A 功能，同时想让 Codex 修 B bug。
这时让 Codex 在工作树里处理 B bug，可以避免互相污染。

2. 代码重构

重构通常会改很多文件。
如果直接在 Local 里改，失败后清理成本较高。放到工作树里更安全。

3. 探索性任务

比如让 Codex 尝试一种新的实现方案、优化架构、迁移依赖。
这些任务不一定最终采用，适合先在工作树中实验。

4. 自动化任务

Codex 的 automations 可以在后台定期运行。
如果任务会产生代码改动，最好放在独立工作树里，避免影响当前本地开发。

5. 多任务排队

你可以让 Codex 在多个工作树里处理不同任务。
每个任务的改动相互隔离，review 时更清楚。

什么时候不适合用工作树？

工作树不是所有场景都必须用。

以下情况可以直接用 Local：

• 只是问代码问题，不需要改文件
• 只做很小的修改
• 你希望 Codex 直接基于当前本地环境操作
• 项目启动环境复杂，工作树里不容易跑起来
• 你的改动依赖很多未提交、被 .gitignore 忽略的本地文件

尤其要注意：工作树只会继承 Git 管理的文件。
如果某些配置、依赖、环境文件没有提交到 Git，工作树里可能没有这些内容，导致项目跑不起来。

本地环境配置

因为工作树在另一个目录里运行，所以它可能缺少依赖或构建产物。

Codex 支持为工作树配置 local environment，也就是本地环境脚本。比如 TypeScript 项目可以配置：

npm install
npm run build

这样每次 Codex 创建新的工作树时，会自动执行初始化脚本，让工作树具备基本运行条件。

对于前端项目，还可以配置常用 actions，比如：

npm start
npm test
npm run build

这样 Codex 或你自己就能更方便地在工作树里运行项目、测试和构建。

最佳实践

1. 一个任务一个工作树

不要把多个不相关任务混在同一个工作树里。
例如“修登录 bug”和“重构缓存模块”最好分开做，这样 diff 更干净，也更容易回滚。

2. 先小任务试用

第一次用工作树时，不要直接交给 Codex 一个巨大重构。
可以先让它修一个小 bug、加一个测试、整理一个函数，熟悉流程后再处理复杂任务。

3. 给 Codex 明确验收方式

不要只说“优化一下代码”。
更好的写法是：

请在工作树中重构这个模块，保持外部行为不变。
完成后运行 npm test，并说明改动点、风险点和验证结果。

Codex 越知道如何验证结果，输出越可靠。

4. 给工作树准备 setup 脚本

如果项目需要安装依赖、生成类型、构建产物，建议把这些步骤配置到 local environment 中。
否则 Codex 可能会因为缺少依赖而无法运行测试。

5. review 后再合并

工作树的意义不是让你无脑接受 Codex 的改动，而是让改动更容易隔离和审查。
建议重点看：

• 改动是否超出任务范围
• 是否误删代码
• 是否引入不必要的复杂度
• 测试是否真的跑过
• 是否影响当前分支上的其他功能

6. 定期清理不用的工作树

如果经常使用自动化或并行任务，工作树可能越来越多。
不再需要的线程和工作树要及时归档或清理，避免项目目录混乱。

总结

Codex 工作树的核心价值是：隔离 AI 改动，让 Codex 可以并行工作，而不干扰你的本地开发。

它特别适合修 bug、重构、探索方案、自动化任务和多任务并行。
但它也有前提：项目最好是 Git 仓库，并且依赖、配置和启动方式要能在独立目录中复现。

如果你只是偶尔让 Codex 改一两行代码，工作树不是必须。
但如果你开始把 Codex 当成一个长期协作的 coding agent，工作树会是非常值得掌握的功能。