Codex 工作树（Worktree）是 OpenAI 基于 Git worktree 机制提供的并行开发功能，允许同一 Git 仓库下的多个 AI 编程任务各自拥有独立的文件目录，同时共享底层提交历史与分支元数据。截至 2026 年 11 月 12 日，OpenAI 官方文档已完整涵盖工作树创建、默认 detached HEAD 处理、分支保留、双向 Hand off 交接及自动清理恢复等全流程机制；对于本地托管工作树，开发者还可通过初始化脚本与 .worktreeinclude 自动配置运行依赖和被 Git 忽略的本地环境变量。
在实际开发中，当新功能写到一半却突然需要排查线上 Bug 时，把两个任务塞进同一个目录往往会导致文件互相覆盖、依赖频繁重装，甚至污染尚未提交的草稿。借助 Codex 工作树，你可以让原有目录继续推进功能开发，同时为 Bug 修复单独开辟一块干净的物理工作区，两条线并行处理，互不干扰。
工作树与 Git 分支分别管理什么？
许多开发者容易把“新建工作树”和“切换 Git 分支”混为一谈，实际上两者解决的是不同维度的隔离问题：
- Git 分支（Branch）管理的是一条向前的提交时间线。如果只在单一工作区里频繁切换分支，本地文件状态会被反复覆盖，未提交的改动也需要频繁暂存（Stash）。
- Codex 工作树（Worktree）管理的是独立的物理检出目录。同一个仓库可以同时挂载多个目录，每个目录下存放着对应任务的文件副本。
在使用前，有三个技术边界需要明确：
- 必须基于 Git 仓库：普通本地文件夹无法通过直接勾选“Worktree”获得隔离能力，项目必须已经纳入 Git 版本控制。
- 合并冲突依然存在：多个工作树共享同一套 Git 历史，各自修改完成后仍需独立审查与提交；如果两个并行任务改动了同一段核心业务逻辑，后期合并分支时依然需要手动解决冲突。
- 仅限文件系统隔离：工作树只负责把代码目录分开，本地数据库、外部接口以及开发服务器占用的网络端口（如
localhost:3000）并不在隔离范围内，需要按项目实际情况错开配置。
准备工作：为 Codex 接入大模型 API
在正式派发并行任务前，需要先为 Codex 配置可用的大模型推理通道。目前常见的接入方式分为官方直连与托管中转两类，开发者可根据网络环境与账单习惯自行选择：
1. OpenAI 官方订阅与官方 API 接入
- ChatGPT 账号订阅直连：在 ChatGPT 桌面端（Codex 面板）或命令行工具中，直接使用已开通 Plus、Pro 或 Team 订阅的官方账号完成授权登录即可。这种方式无需手动维护密钥，适合习惯官方原生体验的用户。
- 官方 API Key 接入：若希望按实际 Token 消耗计费，可在系统环境变量中配置
OPENAI_API_KEY，或在本地配置文件~/.codex/config.toml中指定官方接口端点与目标模型。
2. 国内托管中转站接入（以 4SAPI 为例）
由于 Codex 底层遵循标准的 OpenAI 兼容协议，除了官方通道外，开发者也可以通过自定义端点接入国内托管中转平台（例如 4SAPI）。
- 配置方法：在 4SAPI 控制台创建并获取专属
API Key与接口地址（Base URL），随后在本地终端环境变量中写入OPENAI_BASE_URL与OPENAI_API_KEY，或在~/.codex/config.toml中将自定义 Provider 指向该中转地址即可完成接入。 - 核心优势：相较于单一官方渠道，采用此类托管中转方案的主要优势在于国内网络环境可低延迟直连（省去复杂的网络代理配置）、按实际调用量计费（降低固定月费门槛），以及单个接口兼容多款主流大模型（方便根据任务复杂度在轻量修复与深度重构之间切换模型）。
在桌面端 Codex 中创建工作树任务
完成模型接入后，即可在桌面端为新任务分配独立工作区。创建时的起始分支与是否携带本地未提交改动，决定了 AI 任务从哪一份代码快照起步：
- 打开 ChatGPT 桌面应用并切换到 Codex，在新建对话输入框下方选择 Worktree，接着指定起始 Git 分支。
- 新工作树默认从所选分支的最新提交（
HEAD）检出代码；如果勾选携带本地改动，Codex 会自动将当前工作区未提交的修改同步应用到新目录中。 - 若项目已配置本地环境初始化脚本，可一并勾选执行。提交指令后，Codex 会自动生成对应目录并开始执行任务。
为了让首轮执行更可控，建议在指令中明确审查边界与验证要求，例如：
> 在当前工作树中排查登录测试用例失败的原因。请先列出排查证据与修改计划，仅改动相关业务文件；修改完成后运行对应单元测试，并说明具体改动点及尚未验证的边界情况。
当 AI 完成初步修改后，建议先打开该工作树内置的终端，执行以下只读命令核对当前所处位置与仓库状态，再启动本地服务或测试套件：
默认 detached HEAD 状态下，如何安全保留工作成果？
Codex 新建的托管工作树默认处于 detached HEAD（游离头指针）状态，即当前工作区直接指向某一次具体提交，而未绑定任何命名分支。
这样设计的好处是轻量——Codex 在后台并行开启多个实验性任务时，不必为每个临时目录预先创建大量分支。看到 detached HEAD 并不意味着代码处于丢失风险中，但当你决定保留修改并进入交付流程时，需要执行以下收尾动作：
- 创建正式分支：如果打算留在该工作树继续开发，点击对话窗口顶部的 Create branch here，输入规范的分支名（例如
codex/login-fix），随后即可正常审查代码差异（Diff）、提交变更并推送发起 Pull Request。 - 联动本地编辑器：点击顶部的 Open 入口，可以直接调用你常用的本地 IDE 打开该工作树目录，方便利用熟悉的调试工具进行人工复核。
需要注意的是，Git 规则默认不允许同一个命名分支同时被两个不同的工作树检出。多个工作树可以从同一个历史提交起步，但切勿尝试将同一个分支同时挂载在两个目录里并行编辑。
使用 Hand off 在 Worktree 与 Local 之间无缝交接
当某个项目在本地同一时间只能运行一套服务实例，或者你希望把后台跑通的代码拉回日常主开发目录继续精细调整时，可以使用对话顶部的 Hand off 功能。
- 双向流转：
Hand off能够将当前对话上下文连同代码修改状态，在 Worktree 与 Local（主工作区）之间平滑交接，底层所需的 Git 状态切换均由官方流程自动托管。 - 持续关联：已经推进到一半的 Local 任务也可以反向交接至工作树中继续执行；只要保持在同一个对话窗口内，后续随时可以再次交接回原环境。
- 避坑提示：如果在手动操作 Git 时遇到
branch is already used by worktree报错，应先通过git worktree list排查分支被哪个目录占用。只要目标是回到主目录继续同一项任务，优先点击界面上的Hand off，避免在命令行强行检出冲突分支。
交接完成后，别忘了在目标环境中重新核对一次工作路径、Git 差异以及运行依赖是否完整。
环境缺少文件？检查初始化脚本与 .worktreeinclude
新工作树拥有了完整的源码文件，并不等同于具备了可运行环境——第三方依赖包和本地密钥文件往往还需要额外准备。
1. 自动执行环境设置脚本
根据 OpenAI 本地环境文档，开发者可以在项目根目录的 .codex 文件夹下配置环境设置脚本（该配置可纳入 Git 团队共享）。每次通过 Codex 创建新的工作树对话时，系统会自动触发该脚本，自动完成诸如 npm install 或数据库迁移等初始化步骤。
2. 自动复制被忽略的本地配置（.worktreeinclude）
像 .env.local 这类包含本地环境变量的文件通常被写入了 .gitignore，新建工作树时不会被 Git 自动带出。此时可以在仓库根目录新建一个名为 .worktreeinclude 的规则文件，列出需要自动同步过去的被忽略路径：
关于这项复制规则，有几项细节值得留意：
- 适用范围：仅对本地 Codex 托管工作树生效，不适用于远程云端工作树，也不适用于你在终端手动通过
git worktree add创建的目录。 - 安全边界：它不会把其他未跟踪的临时文件一股脑复制过去，同时会自动跳过源目录中的符号链接（Symlink），且绝不会覆盖目标目录中已经存在的同名文件。
磁盘占用管理、自动清理与快照恢复
由于每个工作树都会独立存放源码副本、依赖包及构建缓存，长期高频使用后需要留意本地磁盘空间。
截至 2026 年 11 月核验的官方规则，Codex 默认在本地保留最近 15 个托管工作树，开发者可在设置面板中自行调高上限或关闭自动清理。在清理机制触发时，已置顶（Pinned）的对话以及仍处于运行状态的对话所关联的工作树会被自动豁免，不会被误删。
当你主动归档（Archive）某条对话，或工作树总数达到上限触发旧目录回收时，底层物理目录会被清理以释放空间，但聊天记录仍会保留；在删除目录前，Codex 会自动保存一份工作快照，日后重新打开该归档对话时，界面上会提供恢复入口以便找回当时的代码现场。
纵观整套工作流，高效驾驭 Codex 工作树的关键在于理顺操作节奏：先配好顺手的模型 API 通道，再选定代码起点、隔离物理目录、补齐运行依赖，经过独立验证后创建分支或交接回本地合并。本文涉及的 Git 机制与状态查看命令已在独立临时仓库实测验证，界面交互与托管规则均依据截至 2026 年 11 月 12 日的 OpenAI 官方文档核对整理。
参考资料
- OpenAI 工作树官方文档：
https://learn.chatgpt.com/docs/environments/git-worktrees - OpenAI 本地环境官方文档：
https://learn.chatgpt.com/docs/environments/local-environment - 4SAPI接入教程官方文档：
https://4sapi.apifox.cn/
