Codex Git Worktree 是把 Codex 聊天任务放进独立 Git 工作树的开发方式：每个任务拥有自己的文件检出和工作目录，同时共享仓库的提交与分支元数据，从而支持多个任务并行推进而不互相覆盖。OpenAI 官方文档将它定义为 Codex 的后台隔离环境，默认使用 detached HEAD，并通过 Handoff 在工作树与本地检出之间安全转移任务。

Codex Git Worktree 是什么

Codex Git Worktree 的核心价值是把“对话隔离”和“代码隔离”绑定在一起。

它建立在 Git 原生 git worktree 之上：主工作树与链接工作树各自有文件、HEAD 和 index。

两者共享提交对象、分支引用等仓库元数据。

这意味着你可以让一个 Codex 任务修复线上缺陷，同时让另一个任务重构模块或补测试。

一个任务的未提交文件不会出现在另一个工作树里，适合长任务、实验性修改和需要频繁切换上下文的团队。

根据 OpenAI 官方文档（2026），Codex 管理的工作树默认创建在 $CODEX_HOME/worktrees。

它以启动时所选分支的 HEAD 提交为起点。

默认工作树不是分支检出，而是 detached HEAD；这也是 Codex 能够同时创建多个独立任务环境的关键。

Local、Worktree 与 Handoff 的区别

Codex 的本地检出与工作树不是两套 Git 系统，而是同一仓库下的两种工作位置。

模式

文件位置

适合场景

主要注意点

Local

你平时打开的仓库目录

需要现有 IDE、开发服务器或本地依赖

会直接影响当前检出

Worktree

Codex 创建的独立目录

并行任务、后台任务、隔离实验

默认是 detached HEAD

Handoff

在两者之间移动聊天和代码

先后台执行，再回本地检查

由 Codex 处理 Git 迁移步骤

OpenAI 文档把 Local 视为前台、Worktree 视为后台。

你可以在工作树中完成验证。

当任务需要人工检查、启动现有服务或使用常用 IDE 时，点击 Handoff 转回 Local。

任务再次交回 Worktree 时，Codex 会返回同一个关联工作树。

如何启动一个 Codex Worktree 任务

启动工作树任务通常只需要四步：

  1. 在新聊天的环境选择中选择 Worktree。

  2. 选择起始分支，可以是 main、功能分支，或包含未提交改动的当前分支。

  3. 提交任务提示词，Codex 创建工作树并准备初始检出。

  4. 根据需要继续留在 Worktree，或使用 Handoff 转到 Local。

如果项目需要安装依赖、构建或准备测试数据，可以在项目的 .codex 本地环境中配置 setup script。典型配置如下：

npm install
npm run build

setup script 在 Codex 创建新工作树时运行，能减少“本地能跑、工作树不能跑”的环境差异。

操作按钮也可以放进本地环境配置，让启动开发服务器和测试变成可重复动作。

手动使用 Git Worktree 的命令

即使不通过 Codex 界面，Git 原生命令也适合管理长期工作树。

下面的流程会从 main 创建一个名为 fix/login-timeout 的独立分支和目录：

git fetch origin
git worktree add ../project-login-timeout -b fix/login-timeout origin/main
cd ../project-login-timeout
git status

日常检查和清理使用以下命令：

git worktree list
git worktree remove ../project-login-timeout
git worktree prune

list 用于查看路径、提交和当前分支；remove 适合清理干净的工作树。

如果目录被手动删除后留下过期管理信息，再运行 prune。

Git 官方文档还提醒，未提交或未跟踪文件会阻止普通 remove。

只有确认不需要这些文件时才使用 git worktree remove --force。

并行任务的分支策略

同一个 Git 分支不能同时在两个工作树中被检出，这是 Git 为避免同一分支引用发生竞争而设置的保护。

OpenAI 官方文档给出的典型报错是：

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

更稳妥的策略是“一项任务一个分支”：

  1. 只读分析或快速实验：使用 Codex 默认 detached HEAD。

  2. 需要保留改动：在 Worktree 中创建唯一分支，例如 codex/fix-cache。

  3. 准备回本地：优先使用 Handoff，不要强行在 Local 再次检出同一分支。

  4. 合并完成后：删除工作树，再按需执行 git worktree prune。

若多个任务都从同一个 main 提交开始，它们可以并行修改不同文件。

真正合并时仍应通过测试、代码审查和常规 Pull Request 流程解决冲突。

被忽略文件如何进入 Codex 工作树

Codex 管理的工作树从 Git 检出开始，因此已跟踪文件会自动存在；.gitignore 忽略的本地配置不会自动复制。

需要共享本地开发配置时，可在仓库根目录创建 .worktreeinclude：

# .worktreeinclude
.env
.env.local
config/secrets.json

OpenAI 文档说明，Codex 只复制匹配 .worktreeinclude 的忽略文件。

它不会覆盖工作树里已经存在的文件，也不会复制源文件符号链接。

敏感文件仍应遵循团队的密钥管理策略，.worktreeinclude 不是权限控制机制。

如果任务还需要把外部工具能力接入 Agent，可把相关 MCP 配置纳入项目的环境准备流程。

例如七牛云 MCP 服务的文档可作为一个标准化能力编排参考，但不要把访问密钥提交到仓库。

工作树清理与恢复

工作树会占用独立的依赖目录、构建缓存和生成文件，因此磁盘管理必须纳入工作流。

OpenAI 官方文档显示，Codex 默认保留最近 15 个 Codex-managed worktrees。

它会优先保留进行中的任务、置顶聊天和永久工作树。

当关联聊天被归档，或工作树超过配置上限时，Codex 可能自动删除管理工作树。

删除前会保存快照，重新打开聊天时可以选择恢复。

需要长期保留的环境应创建 permanent worktree，它不会因聊天归档而自动删除。

常见问题

Q：Codex Worktree 和普通 git clone 有什么区别？

Worktree 与主仓库共享 Git 对象和元数据，创建成本通常低于再次 clone。

但每个工作树仍有自己的文件、HEAD 和 index。

它更适合同一仓库的并行分支工作。

Q：为什么我不能在本地检出工作树里的分支？

因为 Git 不允许同一分支同时被两个工作树检出。

先使用 Handoff 把聊天和代码移回 Local，或在工作树中切换到另一个分支，再执行本地检出。

Q：什么时候应该用 detached HEAD？

只读分析、临时实验和不需要直接推送的 Codex 任务适合 detached HEAD。

需要提交、推送或创建 Pull Request 时，应在工作树中创建明确的功能分支。

Q：.worktreeinclude 可以复制所有本地文件吗？

不可以。它只匹配被 Git 忽略的路径，跟踪文件不应列入其中。

Codex 还会跳过源符号链接，并且不会覆盖已经存在的目标文件。

Q：工作树被删除后，聊天记录还在吗？

聊天可以保留在历史记录中。

对 Codex-managed worktree，Codex 会在删除前保存快照，并在重新打开聊天时提供恢复选项。

永久工作树则不会因聊天归档自动删除。

结论

Codex Git Worktree 适合把多个开发任务拆成互不干扰的执行单元。

用 detached HEAD 保持轻量实验，用独立分支承载可交付改动，用 Handoff 在后台与本地之间转移上下文。

Git 官方文档负责解释底层的共享元数据和分支限制。

OpenAI 官方文档则补充了 Codex 的目录、清理、环境脚本和恢复行为。

本文基于 OpenAI 官方文档与 Git 官方 git-worktree 文档截至 2026-09-10 的内容整理。

Codex 界面和默认设置可能随版本更新，实际使用前应复核当前文档。

延伸资源