发布日期：2026-11-12｜分类：AI与智能服务｜资料核验截至2026-11-12

Codex工作树是OpenAI基于Git worktree提供的独立工作目录，供同一项目的多个任务并行使用。它们共享仓库历史与分支信息，各有独立的文件。截至2026年11月12日，官方文档已覆盖Worktree创建、默认detached HEAD、分支保留、Handoff交接及清理恢复。本地托管工作树还可通过环境设置脚本和.worktreeinclude准备依赖与被忽略的配置。上手时先选对起点，再确认目录、运行测试和处理成果，文件隔离之后仍需要审查与合并。

你正在开发一个功能，临时又来了一个Bug。让两个任务挤在同一个目录里，可能会同时改文件、重装依赖，或者互相影响还没提交的内容。

Codex工作树适合处理这种情况：功能开发继续留在原来的目录，Bug修复放进另一个工作目录。你可以同时推进，再分别检查结果。

工作树与分支，分别管理什么

工作树提供独立的文件目录，分支记录一条可继续推进的提交线，两者可以配合使用。

只在同一个目录里切换分支，工作区还是那一个，需要不断切换当前代码状态。使用Git工作树后，同一仓库可以同时拥有多个检出目录，每个目录放着自己的文件。

据OpenAI截至2026年11月的工作树文档，这项功能要求项目属于Git仓库。普通文件夹不能仅凭选择“Worktree”就获得Git工作树；先确认项目已纳入版本控制。

多个工作树共享提交与分支等仓库信息，但各自的代码修改需要分别审查、测试和提交。文件目录分开之后，改到同一业务逻辑的任务在合并时仍可能产生冲突。

还有一个边界值得先记住：工作树提供的是代码目录隔离。数据库、外部服务以及开发服务器端口，需要按项目的运行方式另外安排。

在桌面端Codex里创建一个工作树任务

创建工作树时，起始分支和是否携带本地改动，会决定新任务从哪份代码开始。

按当前官方文档，先在ChatGPT桌面应用中选择Codex，在新聊天输入框下选择Worktree，再选起始Git分支。

新工作树从所选分支的HEAD提交开始；如果选择携带本地改动，Codex再把未提交改动应用到新目录。主分支、功能分支或当前工作状态，应按任务需要明确选择。

如果项目已经配置本地环境，可以一并选择，让新工作树运行环境设置脚本。提交任务后，Codex会创建对应目录并开始工作。

第一条任务可以写得具体一点：

在这个工作树里定位登录测试失败的原因。先列出证据和计划，只修改相关文件；完成后运行对应测试，说明修改了什么、还有哪些问题未验证。

开始审查时，可以在该工作树的集成终端检查：

pwd
git status --short --branch
git worktree list

先确认自己身处哪个目录、当前Git状态是什么，再启动开发服务或运行测试。上述命令用于查看状态，不会创建、切换或删除工作树。

默认detached HEAD，怎样保留工作成果

Codex新建的托管工作树默认处于detached HEAD，也就是当前检出指向某个提交，而非命名分支。

这让Codex可以建立多个工作目录，起步时不必为每个任务立即创建分支。看到detached HEAD并不代表代码已经丢失，但准备继续维护或提交成果时，需要明确下一步。

如果打算一直在这个工作树验证和开发，可以使用聊天顶部的Create branch here创建分支，例如codex/login-fix，再审查差异、提交改动、推送并创建PR。

也可以通过顶部“Open”入口，在这个工作目录打开常用编辑器，继续运行测试。分支名、改动范围和验证结果都确认后，再把它交给后续评审流程。

需要注意，Git正常情况下不允许同一个分支同时被多个工作树检出。多个工作树可以从相同提交开始，但不应把同一个分支同时留在不同目录里编辑。

交接回Local，用Hand off完成

Handoff用于将聊天及其代码在Local与工作树之间交接，方便回到日常开发环境继续处理。

如果你只能运行一套应用实例，或者想在原来的编辑器窗口检查改动，可以在聊天顶部选择Hand off，将任务交接到Local。官方流程会处理交接需要的Git操作。

反过来，已经在Local里进行的任务，也可以交接到工作树，在后台继续推进。按当前文档，同一个聊天保留关联工作树，之后交接回去时会回到那个环境。

遇到“branch is already used by worktree”一类提示，应先用git worktree list查看分支占用。如果目的是回到Local继续同一个任务，优先使用Handoff流程，避免在两个目录里强行检出同一分支。

交接后仍应检查当前目录、Git差异和测试结果。聊天移动到了另一个工作位置，运行依赖与本地配置是否齐全，也要在目标环境里确认。

环境缺文件，先检查依赖与.worktreeinclude

工作树拥有代码文件后，还需要准备该项目实际运行所需的依赖和本地配置。

OpenAI本地环境文档说明，环境设置脚本会在创建新工作树聊天时自动执行，配置保存在项目根目录的.codex下，可以纳入Git。可以把项目既有的依赖安装和初始化步骤写入脚本，减少每次重复准备。

本地配置还有另一种情况：.env.local被Git忽略，因此普通检出不会自动带上它。当前文档支持在仓库根目录添加.worktreeinclude，列出需要复制的被忽略路径，例如：

# .worktreeinclude
.env.local

这项复制规则针对本地Codex托管工作树，不适用于远程工作树或你通过命令行自行创建的Git工作树；也不会把其他未跟踪文件一并复制。它跳过源符号链接，不覆盖目标目录已存在的文件。

先确定新工作树真正需要哪些本地配置，再列入规则。依赖安装、文件复制和服务启动分别处理，比把“代码在了”当作“环境好了”更容易定位问题。

本文只在独立临时Git仓库验证Git机制与查看命令；Codex界面、Handoff和自动复制规则依据官方文档核对，未在用户项目中实际创建或移动任务。

工作树会占磁盘，清理与恢复也有规则

Codex托管工作树有自己的文件、依赖和构建缓存，任务多起来后需要关注磁盘占用。

截至2026年11月核验的官方文档，默认保留最近15个Codex托管工作树，可以在设置中调整上限或关闭自动删除。关联置顶聊天、仍在进行中的聊天，其工作树不会被自动清理。

归档关联聊天，或达到配置上限需要清理旧目录时，托管工作树可能被删除。官方说明，删除前会保存工作快照，重新打开聊天时提供恢复入口；聊天历史可以保留，底层目录则可能已经清理。

这些是Codex托管工作树的管理规则，不能直接套到手动创建的Git工作树上。准备收尾时，先记录当前分支、检查提交和验证结果，再决定是否归档。

从OpenAI工作树与本地环境文档看，使用顺序可以落在几件具体的事上：选起点、隔离文件、准备环境、验证改动，再创建分支或交接回Local。本文资料截至2026年11月12日。

参考资料

相关文章

七牛云产品