Codex Worktree 实战：多个 AI 任务并行开发，互不污染代码

一个仓库里同时跑三个任务：fix/auth-expired-session、test/payment-webhook、docs/setup-node20。主目录 git status 混在一起：登录 bug 的改动、测试 fixture 文件、README 的 Node 20 说明。三类改动都在一个 checkout 里，你已经分不清哪一块能单独提交，哪一块还会影响其他人。

这不是多任务并行的抽象问题，而是 Git checkout 被污染后的真实后果。Codex app 的 Worktree 模式把不同任务拆到不同目录和分支，让每条工作线的 diff 都可验收、可合并、可回滚。

Local / Worktree / Cloud：三种模式怎么选

Codex app 支持三种运行模式。Local 和 Worktree 都在本机运行（官方文档明确：“Both Local and Worktree threads will run on your computer”），Cloud 则在远程环境。

模式	运行位置	修改目标	适用场景	风险与代价
Local	本机	主 checkout	单任务、稳定开发	直接改主目录，未完成工作会被污染
Worktree	本机	独立目录 + 分支	多任务并行、尝试新想法	需配置 setup scripts 和 .worktreeinclude
Cloud	远程	云环境	CI/CD、远程构建	单独文章展开

Worktree 模式适合并行跑独立任务或尝试新想法。每个 thread 有自己的目录和分支，主 checkout 不受影响。Local 模式简单，但多个任务混在一起后很难拆分提交；Cloud 模式则完全脱离本机，适合 CI/CD 和远程构建。

选择逻辑：单任务优先 Local，多任务并行或尝试性工作用 Worktree，远程任务用 Cloud。

Codex app 的 Worktree 模式详解

Worktree 创建与 Handoff

在 Codex app 里创建 Worktree thread 的流程：

1. 创建新 thread
2. 选择 Worktree 模式（UI 入口名称截至 2026-06-18 可能变化）
3. 选择起始分支，或默认在 detached HEAD 上工作
4. 提交第一个 prompt
5. Codex 在独立目录开始工作

默认情况下，Codex 在 detached HEAD 上工作，这样可以一直在 worktree 里操作并创建分支。Handoff 功能用于在 Local 和 Worktree 之间移动 thread 和代码。

Handoff 场景：

Worktree 到 Local：任务完成后，先在 worktree 里创建 branch（如果还在 detached HEAD），然后用 Handoff 移回 Local，最后 merge 或创建 PR。

Local 到 Worktree：想把未完成工作移到隔离环境继续，避免主 checkout 被污染。

Handoff 不只是切换目录，还会把当前 thread 的上下文（prompt 历史、未完成改动）一并移动。

Codex-managed worktree 的特性

Codex-managed worktrees 有几个特殊行为：

默认位置：$CODEX_HOME/worktrees

默认保留数量：15 个（截至 2026-06-18 官方文档），超过会自动清理

Permanent worktree：手动创建的 worktree 不会自动删除

Branch 限制：Git 限制同一 branch 不能同时被多个 worktree checkout，尝试切换会报错

规则继承：AGENTS.override.md 自动复制到 worktree，保持项目规则一致

这些行为意味着：worktree 数量有限制，超过会自动清理；同一 branch 不能并行操作；项目规则会自动继承。

.worktreeinclude 解决忽略文件问题

Worktree 默认只继承 Git tracked files，.gitignore 里的文件不会自动随 Handoff 移动。常见问题：worktree 里缺 .env、.env.local、依赖缓存、本地配置文件。

解决方式：在项目根目录创建 .worktreeinclude 文件，明确列出需要复制的忽略文件。示例：

.env
.env.local
node_modules/.cache

这样 Handoff 时，.gitignore 里的文件也会被复制到 worktree。

Setup scripts：让 worktree 里的项目能跑起来

Worktree 位于不同目录，可能缺依赖或没有 check in 的文件。Setup scripts 在创建新 worktree、新 thread 开始时自动运行，确保环境可用。

配置步骤：

1. 在 Codex app 的 Local environments 中配置 setup steps
2. 创建 .codex 目录存放配置文件
3. 编写平台特定脚本

Node.js 项目示例：

# .codex/setup.sh
npm install
npm run build

Python 项目示例：

# .codex/setup.sh
pip install -r requirements.txt
python manage.py migrate

Setup scripts 在每个新 worktree 创建时自动执行，避免手动安装依赖。注意：配置 UI 和文件格式截至 2026-06-18 可能更新，需要对照官方文档。

不用 Codex app，Plain Git worktree 也能隔离

CLI/终端路径下，也可以直接用 Git worktree 命令创建隔离目录，然后在对应目录启动 Codex。不需要 Codex app 的托管功能，但需要手动管理。

Git Worktree 常用命令：

# 创建新 worktree 和分支（官方用例风格）
git worktree add ../analysis-highway-eda -b analysis/highway-eda

# 创建新 worktree 基于现有分支
git worktree add ../task-b existing-branch

# 列出所有 worktrees
git worktree list

# 删除 worktree
git worktree remove ../task-a

# 清理过期 worktree
git worktree prune

对比 Codex-managed 和 Plain Git：

特性	Codex-managed	Plain Git
创建方式	App UI 自动	git worktree add
位置管理	$CODEX_HOME/worktrees	手动指定
清理策略	自动保留 15 个	手动 prune
Handoff	App 内切换	手动 cd 到目录
Setup scripts	自动执行	手动配置

Plain Git worktree 适合喜欢 CLI 的开发者，但需要手动处理依赖安装、环境配置和清理工作。Codex-managed worktree 则把这些自动化。

Automations 后台任务要不要用 worktree

Git 仓库中的 automation 可以运行在 local project 或 dedicated background worktree。选择取决于任务类型和风险控制。

判断逻辑：

Local 模式适合单次任务、临时测试。直接改主 checkout，未完成工作会被污染。如果你正在编辑文件，后台 automation 可能直接修改同一文件。

Worktree 模式适合重复任务、定时任务。隔离 automation changes 与 unfinished local work。automation 在独立目录运行，不影响主 checkout。

风险提示：

Automations 使用默认 sandbox settings（截至 2026-06-18 可能变化）

Full access 权限下，后台 automation 风险更高，建议必须用 worktree

不要把后台重复任务直接跑在 Local

选择原则：单次临时任务可以 Local，重复任务和 full access 下必须用 worktree。

哪些任务适合并行，哪些必须串行

官方用例建议把不同探索拆到不同 worktree。实际操作时，需要判断任务之间的文件冲突和依赖关系。

任务并行策略判断表：

任务类型	并行可行性	原因	建议
独立文件修复（不同模块）	适合并行	无文件冲突风险	同时开多个 worktree
新功能开发（独立组件）	适合并行	模块边界清晰	每个 worktree 一个组件
同一文件多处修改	必须串行	合并时会冲突	按优先级逐个完成
有依赖关系的任务	必须串行	前者是后者输入	完成前任务再开始后任务
文档更新	适合并行	通常独立文件	可与其他任务并行

并行原则：

从两个互不依赖的小任务开始，不要一上来开五六个

任务数量控制在 3-4 个以内（降低验收成本）

每个任务有明确的验收标准

不鼓励过度并行。并行任务多了，验收成本和合并冲突风险都会上升。

任务卡片模板：每个 worktree 写清楚做什么

每个 worktree 开始前，建议写清楚任务描述，方便验收和追踪。

任务卡片示例：

Goal: "修复 auth 模块的 session expired bug"
Context:
  - "用户登录后 session 30 分钟过期，但前端没有提示"
  - "相关文件：src/auth/session.js、src/components/AuthProvider.jsx"
Constraints:
  - "不改数据库 schema"
  - "不引入新依赖"
Done when:
  - "session 过期时前端显示提示"
  - "npm test 通过"
  - "手动测试登录流程"

Branch/Worktree: "fix/auth-expired-session"
验收命令: "npm test && npm run lint"

填写要点：

Goal：一句话描述目标

Context：提供上下文（文件、模块、背景）

Constraints：明确边界（不改什么、不做什么）

Done when：可验证的完成标准

Branch/Worktree：命名要清晰（task-type/module-description）

验收命令：具体可执行

这样每个 worktree 的任务有清晰边界，验收时对照 Done when 检查即可。

合并队列：逐个 review、测试、合并

并行任务完成后，不要一次性糊到 main。建议按风险排序，逐个 review、测试、合并。

合并队列步骤：

1. 按风险排序 worktree（最小风险优先）
2. 对第一个 worktree：
   • 跑验收命令（测试、lint）
   • 检查 diff（确认改动范围）
   • 创建 branch（如果还在 detached HEAD）
   • Review diff（参考 PR review 最佳实践）
3. 合并到 Local 或创建 PR：
   • Local 合并：Handoff 回 Local 后 merge
   • PR 合并：创建 PR，等待 CI 和 review
4. 对下一个 worktree 重复上述步骤
5. 全部完成后，合并到 main branch

验收清单：

验收命令通过（测试、lint）

Diff 检查：改动范围符合预期

Review guidelines：无敏感文件、无硬编码

CI 通过（如果有）

手动测试流程

风险提示：

不承诺自动合并多个 worktree 的结果

同一文件多处修改需要手动解决冲突

始终保留人工 review 和测试环节

合并队列的核心是让每条工作线的 diff 可验收、可回滚，而不是一次性提交所有改动。

排障清单

”branch already used by worktree” 错误

原因：branch 被其他 worktree 占用

解决方式：

使用 git worktree list 查看哪些 branch 已被占用

选择其他 branch 或删除占用该 branch 的 worktree

worktree 里代码跑不起来

原因：缺少依赖或配置文件

排查步骤：

检查 .env、.env.local 是否存在（可能没有复制）

检查依赖是否安装（node_modules、venv）

检查配置文件是否完整

解决方式：

配置 .worktreeinclude 复制忽略文件

配置 Setup scripts 自动安装依赖

worktree 空间膨胀

原因：频繁 automations 创建很多 worktrees

解决方式：

Archive 不再需要的 automation runs

手动 git worktree prune 清理过期 worktree

检查 Codex app 设置中的 worktree 保留策略（截至 2026-06-18 可能有变化）

agent 创建的 worktree 与 UI/thread context 不同步

原因：agent 自动创建 worktree 时可能绕过 App UI

解决方式：

使用 git worktree list 查看所有 worktrees

在 App 中手动检查 thread 与 worktree 的绑定

避免让 agent 自动创建 worktree，改用 App UI 手动创建

排障的核心是先检查 worktree 状态（git worktree list），再根据错误类型处理。

成本判断：并行任务更容易消耗额度

并行任务更容易消耗更多回合/额度。每个 worktree 都是一个独立 session，Codex 在每个 session 里单独计费。

成本判断：

并行任务数量建议控制在 3-4 个以内

从两个互不依赖的小任务开始（降低验收成本）

每个任务有明确的验收标准，避免无限制迭代

具体价格、额度、plan 信息请参考后续文章（Cost & Quota 管理），不在这里展开未复核的数字。

下一步与延伸阅读

上游文章：

Codex 入口选择：Local / Worktree / Cloud 模式简要介绍

AGENTS.md 项目规则：每个 worktree 如何继承同一套规则