Codex 使用指南

搜索全站

输入关键词开始搜索。
页面更新：事实核验：

Git 隔离

Worktrees

在不打扰 Local 工作区的前提下，让 Codex Desktop 在同一仓库中运行独立任务；完成后留在 Worktree、创建分支，或通过 Hand off 回到 Local。

是什么

Worktree 是什么

Worktree 是同一个 Git 仓库的另一份 checkout。每个 Worktree 有独立的文件目录、索引和工作状态，但共享 commits、branches 等 Git 元数据。它适合隔离并行任务，不是虚拟机，也不是安全沙箱。

flowchart TD A["同一个 Git 仓库"] --> B["Local: 前台工作区"] A --> C["Worktree A: 独立任务"] A --> D["Worktree B: 独立任务"] C --> E["Create branch here / PR"] D --> F["Hand off 到 Local"]
文件目录彼此独立，Git 历史与分支元数据仍属于同一个仓库。

官方事实：Codex Desktop 使用 Git worktrees 支持同一项目中的独立任务，并提供 Local 与 Worktree 之间的 Hand off。完整产品行为见 （外部链接）OpenAI Worktrees。

何时使用

什么时候用 / 不用

  • 适合并行功能、试验性改动、后台任务，或 Local 已有未完成修改时。
  • 优先 Local单文件小修、需要复用当前开发服务器、只能启动一个应用实例，或必须频繁人工调试时。
  • 不要并行多个任务会修改同一 schema、共享 contract 或同一核心文件时，先拆依赖再创建 Worktree。
  • 前置条件项目必须位于 Git 仓库中；非 Git 项目不能创建 Worktree。

Desktop 操作 · 已选择 Worktree

在 Desktop 中创建

1. 选择 Worktree

新建任务时，在输入框下方选择 Worktree。如项目配置了 Local environment（运行 setup scripts 的本地环境配置），可同时选择它；它不是 Local 前台／主 Worktree（main worktree），后者是当前打开的目录。

2. 选择起始分支

选择 main / master、功能分支，或当前含未提交修改的分支。Codex 以所选分支的 HEAD 为基线，并可把选中的本地未提交修改应用到新 Worktree。

3. 提交独立任务

写清目标、允许修改的文件、禁止触碰的范围和验证命令。Codex 创建 managed Worktree；detached HEAD 表示暂时直接停在某个提交上、没有绑定分支名，不会先污染分支列表；若要长期保留成果，再选择 Create branch here。

4. 决定继续位置

验证环境完整时可继续留在 Worktree；需要日常 IDE、现有服务器或人工联调时，通过 Hand off 移回 Local。

交接

Local、Worktree 与 Hand off

留在 Worktree点击 Create branch here在该目录验证、commit、push 和创建 PR该分支不能同时在 Local checkout
回到 Local点击 Hand offCodex 处理两个 checkout 间必要的 Git 操作适合复用 IDE、服务器和本地调试状态
再回 Worktree再次使用 Hand off任务回到原先关联的 Worktree继续保留该任务的后台环境

边界

分支和文件边界

同一分支不能多处 checkout

Git 不允许同一分支同时被多个 Worktree checkout。若准备在 Local 接管，不要手动抢占该分支；优先使用 Hand off，或先让原 Worktree 切到其他分支。

Ignored 文件与 .worktreeinclude

被 .gitignore 忽略的文件不会自然出现在新 checkout。Codex managed Worktree 可通过仓库根目录的 .worktreeinclude 复制必要文件；只列运行所需项，并谨慎对待 .env、密钥和本地配置。

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

不是安全沙箱：Worktree 仍可能共享 credentials、Git 元数据、后台进程、端口、数据库和外部服务。目录隔离不能替代权限控制、互斥写域或服务级隔离。

生命周期

恢复与清理

  • Managed Worktree通常服务于单个任务，适合轻量、可回收的后台工作。
  • Permanent Worktree从项目菜单创建为长期项目，不会因归档关联任务而自动删除。
  • 自动清理Codex 默认保留最近 15 个 managed Worktrees；可在 Settings → Worktrees 调整数量或关闭自动删除。
  • 恢复删除 managed Worktree 前会保存快照；以后打开关联任务时可以恢复。

Worktree 会 checkout 已跟踪文件；被忽略或未跟踪的依赖目录、构建缓存和下载资产不会自动出现，需按项目规则准备。若多个 Worktree 各自生成或下载这些文件，磁盘占用仍可能增长。任务结束后确认分支、PR、验证证据和未提交改动都已妥善保存，再归档或清理。

协作关系

Worktree 与 Subagent 的区别

Worktree隔离目录与 Git 状态一个任务拥有独立 checkout不自动定义谁可以改什么
Subagent隔离上下文、责任与写域一个代理只处理明确子任务不自动获得独立 Worktree
组合使用Worktree 负责环境隔离Subagent 负责执行边界主线程负责依赖、冲突和最终集成

Subagent 的委派合同、推荐拆法和收口规则见 Subagents；按依赖建立并行 lane 的方法见 Issue lanes。

可复制 · Desktop Worktree 已选

可复制示例（已选择 Desktop Worktree）

请在独立 Worktree 中完成这个任务，不要影响当前 Local 工作区。

Base: 当前 main 的最新提交。
Goal: 修复首页卡片布局并补浏览器回归测试。
Writable scope: index.html、assets/site.css、对应测试。
Forbidden: 其他页面、远程 push、合并主分支。
Validation: 静态检查 + desktop/mobile 浏览器测试。
Hand off: 完成后返回 changed files、测试证据和未验证项；
需要复用 Local 开发服务器时先停止并建议 Hand off。

真实实例

真实实例：并行页面修复

场景：Local 正在修改主题控件，同时另一项任务需要重写 Worktree 文档页。两项改动依赖不同文件，可以把文档任务放到独立 Worktree，保留 Local 的未提交主题修改。

开始从包含主题改动所需基线的分支创建 Worktree明确只改文档页、manifest 和测试共享生成器若有重叠则保持串行
验证在 Worktree 内运行页面生成和浏览器测试记录真实 diff 与未验证项不触碰 Local 的工作状态
收口需要独立 PR 时 Create branch here需要复用 Local 预览环境时 Hand off最终由主线程处理集成与冲突