Codex Git Worktree 怎么用？并行开发、Handoff、.worktreeinclude 与清理指南

先说结论：要并行就用 Worktree，要直接改当前目录才用 Local

Worktree 适合让多个 Codex 聊天在同一 Git 项目中并行工作，而不干扰你正在使用的 Local checkout。Local 适合需要立即在现有 IDE、开发服务器和本机环境中检查的任务。

Worktree 只适用于 Git 仓库。它会创建第二个仓库 checkout，每个工作树有独立文件副本，但共享提交与分支等 Git 元数据，因此能并行处理不同分支或 detached HEAD 状态。

本站为第三方中文信息与服务入口，并非 OpenAI 官方。Codex Worktree、Handoff 与清理策略可能随版本调整，请以 ChatGPT Learn 官方文档与桌面应用实际设置为准。

一、Worktree 最适合哪些任务

适合长时间测试、独立功能开发、文档改版、批量修复和计划任务。你可以让一个聊天在后台工作树中运行，同时继续在 Local checkout 编写或审查另一项内容。

不适合没有 Git 的临时目录，也不适合必须依赖当前本地正在运行服务、但又没有可复现初始化步骤的任务。此类工作若强行放进 Worktree，常见问题是依赖、环境变量或本地服务不可用。

二、Local、Worktree 与 Handoff 分别是什么

Local 是日常打开的原始仓库 checkout；Worktree 是由桌面应用从 Local 创建的独立 Git 工作树；Handoff 则负责在两者之间移动聊天及其相关代码状态。

可以把 Local 理解为前台，Worktree 理解为后台。需要用熟悉 IDE 检查、运行单实例服务或共同调试时，把聊天 Hand off 回 Local；需要释放前台继续并行时，再转回 Worktree。

三、怎样创建一个 Worktree 聊天

在新的 Codex 聊天中选择 Worktree，再选择起始分支。起点可以是 main/master、某个功能分支，或带有未暂存本地改动的当前分支；提交任务后，Codex 会创建对应工作树。

默认工作树使用 detached HEAD，这样可同时创建多个工作树而不污染常规分支。开始前先确定任务范围，避免把几个无关功能交给同一个后台工作树。

四、为什么不能在两个工作树同时 checkout 同一分支

Git 限制同一分支同时只在一个工作树处于 checkout 状态。若某工作树已创建 feature/a 分支，Local 或另一工作树再 checkout 同一分支会收到“already used by worktree”错误。

这是为了避免多个目录同时推进同一个可变分支引用而产生竞态、丢失提交或索引混乱。想在 Local 检查该工作，应该使用 Handoff，而不是强行让两个 checkout 占用同一分支。

五、Worktree 中完成任务后怎么保留成果

如果准备持续在该工作树中开发，可在聊天页使用 Create branch here，把当前状态转为一个分支；之后可提交、推送并创建 Pull Request。也可直接打开工作树目录，用 IDE 或集成终端测试修改。

若准备回到日常本地环境验证，选择聊天页的 Hand off 并移动到 Local。Codex 会处理必要 Git 操作，让聊天与代码一起回到前台 checkout。

六、Handoff 不是复制所有机器文件

Handoff 处理聊天和 Git 工作状态，但 .gitignore 中的文件不会自动跟着移动。未跟踪文件、环境变量、数据库、系统依赖和本机凭据都可能仍只存在于原位置。

因此遇到 .env 或依赖缺失时，先确认哪些内容是 Git 跟踪文件、哪些是本地环境。相关排查可参考 https://gptupcn.com/blog/codex-handoff-worktree-missing-env-files/ ，不要为了让任务跑通就把真实密钥提交进仓库。

七、.worktreeinclude 应该怎样使用

本地受管理 Worktree 需要特定被忽略文件时，可在仓库根目录添加 .worktreeinclude，并列出需要复制的忽略路径或类似 .gitignore 的模式，例如 .env.local。只有匹配列表的忽略文件才会被复制。

这项能力只适用于本地 ChatGPT 桌面应用管理的工作树，不适用于远程工作树或命令行手动创建的 Git worktree。它会跳过源符号链接，也不会覆盖新 checkout 中已存在的文件。

八、包含密钥时为什么仍要谨慎

官方示例包含 .env 与 secrets.json，是为了说明复制规则，不是建议把所有秘密分发到每个任务。真正的生产密钥应遵循最小权限、短期有效和独立测试环境原则。

更稳妥的做法是为 Worktree 准备无生产权限的开发配置，或通过受控的密钥管理机制按需注入。任何客服、脚本或第三方工具都不应索取你的 Token、私钥或 Session Cookie。

九、怎样让 Worktree 自动完成初始化

可以在本地环境中配置 setup scripts，让 Codex 创建新 Worktree 时自动安装依赖或运行初始构建。项目级 .codex 配置应放在项目根目录，以便团队共享。

把安装、生成和测试命令写成可重复脚本，比依赖某台电脑的手工状态更稳定。设置方法可参考 https://gptupcn.com/blog/codex-local-environment-setup-scripts-actions-worktree-guide-20260928/ 。

十、受管理 Worktree 与永久 Worktree 的区别

默认的 Codex-managed Worktree 偏向轻量和一次聊天一套环境。聊天若转回后台，通常会回到它原先关联的工作树，适合短到中等时长的独立任务。

需要长期保留的环境，可以在项目侧边栏菜单创建 permanent worktree。永久工作树不会因归档聊天而自动删除，并且可以从同一工作树启动多个聊天。

十一、自动清理会删除什么

工作树会占用仓库文件、依赖和构建缓存空间。官方当前默认保留最近 15 个 Codex-managed Worktree，可在 Settings > Worktrees 调整上限、关闭自动删除或修改 Worktree root。

置顶聊天、仍在运行的聊天和永久工作树不会被自动删除。归档关联聊天或超过配置上限时，较旧的受管理工作树可能被清理；清理前 Codex 会保存快照，重新打开聊天可选择恢复。

十二、手机与远程主机中的 Worktree 在哪里运行

手机不会在本机运行 Worktree；它控制的是已连接电脑或该电脑使用的远程开发环境，仓库、工作树和命令都仍在目标环境中。

因此通过手机批准任务前，应确认实际主机、项目路径和权限。Remote 连接与 SSH Host 的基础关系可参考 https://gptupcn.com/blog/codex-remote-connections-mobile-ssh-handoff-security-guide-20261006/ 。

十三、常见失败排查顺序

创建失败：确认项目位于 Git 仓库并且起始分支存在；代码跑不起来：检查 setup script、依赖和必要忽略文件；分支冲突：确认同一分支没有被另一个工作树占用；磁盘紧张：检查保留上限与旧工作树。

不要在出错后直接删除整个工作树目录。先查看聊天、diff、Git 状态和可恢复快照，保留有价值的改动；必要时先创建分支或提交，再清理。

十四、推荐的并行开发流程

第一步，在 Local 保持你当前稳定工作；第二步，为独立功能启动 Worktree；第三步，用 setup script 初始化并运行测试；第四步，查看 diff 和结果；第五步，选择在 Worktree 创建分支提 PR，或 Handoff 回 Local 做最终验证。

任务越并行，越需要清晰命名、独立分支和验收标准。完成后归档不再需要的聊天，定期检查磁盘占用。更多 Codex 中文实践可从 https://gptupcn.com/ 的技术博客进入。

结语

Codex Worktree 的价值是隔离并行修改，而不是制造更多副本。理解 Local 与后台 Worktree 的分工、Handoff 的 Git 边界、忽略文件与自动清理规则，才能既提高并行效率，又不让环境和分支失控。