Codex CLI 工作树实战：隔离并行开发，安全带回成果

Codex CLI 工作树的最短配置流程

你需要 Codex CLI 0.154.0、本地 Git 仓库，并启用实验性 worktrees 功能。先检查版本，免得在旧版程序中寻找尚不存在的参数。

codex --version
npm install -g @openai/codex@0.154.0
codex features enable worktrees
codex features list

上面的持久化命令会把功能开关写入 Codex 配置。如果只想试用一次，不必改配置，直接在当次调用中加入 --enable worktrees 即可。

接下来，可以启动一个全新的隔离会话、无界面任务，或从已有对话分叉出新会话：

codex --enable worktrees --worktree "Upgrade the test runner and run its suite"
codex exec --enable worktrees --worktree "Find the flaky test and propose the smallest fix"
codex fork --enable worktrees --worktree <session-id> "Try the lower-risk implementation"

交互式分叉中的 <session-id> 是 /status 显示的聊天 ID。0.154.0 版本要求在这里明确提供 ID，不接受 codex fork --worktree --last。

终端界面也支持同一套流程。输入 /worktree 后，可以选择把当前对话迁入新的检出、在其中新建对话，或浏览 Codex 已为该仓库管理的工作树。

Codex CLI 工作树会创建什么

托管工作树，是挂在同一个 Git 仓库上的第二份检出。可以把仓库想成由两个阅览室共用的图书目录：每个房间都能摊开不同页面，但它们引用的是同一组提交和分支。

Codex 会以源仓库已提交的 HEAD 为起点，在 detached HEAD 状态下创建新检出，再把它绑定到新会话。detached HEAD 表示这份检出直接指向某个提交，而不是跟随一个具名分支移动；源检出仍停留在原处。

这个干净起点也带来一个必须正视的结果：原检出里尚未提交的修改不会进入新会话，常见的 .env、node_modules 等被忽略目录也不会过去。OpenAI 在桌面端托管本地工作树的文档中说明了 .worktreeinclude 复制机制，但也明确指出该机制不适用于命令行创建的工作树。因此，走 CLI 流程时，要自行准备任务所需的运行条件。

如果从仓库内部的子目录启动 Codex，托管检出会保留这段相对路径。例如，从 apps/web 启动时，只要已提交的版本中存在该目录，会话就会落在新工作树对应的 apps/web 中。

从启动到保留成果：一套可落地的流程

稳妥的做法分为五个环节：从干净基线开始，确认实际落点，完成任务，检查证据，再明确决定保留还是丢弃成果。

1. 从真正需要的提交开始

--worktree 是布尔开关，不是分支或基线选择器。它以目标仓库当前的 HEAD 为起点。启动前，先切到正确的基础分支，并提交任务需要的源检出改动。也可以用 -C <repo-path> 指向特定的本地检出。

任务彼此独立时，新建会话即可；如果新的尝试依赖原对话中的决策和约束，则应分叉会话。分叉会把对话记录保留到新聊天中，同时将新任务移入隔离检出，第一次尝试也会原样留下，便于比较。

2. 动手编辑前先确认检出位置

让 Codex 在开始时运行 pwd、git status --short 和 git rev-parse --short HEAD。工作目录应指向托管路径，状态应当干净，提交则应与预期的源 HEAD 一致。

这一步能抓住代价最高、也最乏味的一类错误：工作做得很漂亮，基线却选错了。

3. 只安装当前任务通道需要的环境

工作树隔离的是已检出的文件。它不会创建容器、预留端口、克隆数据库或安装依赖。请在托管检出中运行仓库原有的初始化命令。如果多个会话可能争用资源，要为它们分配不同的端口、临时数据库、缓存目录和测试账号。

这是最关键的边界。即使两份 Git diff 都很干净，两个会话若同时迁移同一个开发数据库，或绑定同一个端口，依然会彼此干扰。

4. 检查 diff，并恢复正确的会话线程

在工作树会话内部，可用 /review 检查未提交的修改。如果从另一个终端查看，先运行 /worktree，选择 Browse worktrees（浏览工作树），选中目标检出后再选择 Copy working directory（复制工作目录）。随后运行 git -C "<worktree-path>" status --short、git -C "<worktree-path>" diff --stat 和 git -C "<worktree-path>" diff。

不要运行 codex review --worktree，0.154.0 会拒绝这种参数组合。应在对应会话内审查当前工作树，或把普通审查工具指向刚复制的路径。

稍后继续时，输入 /worktree，选择 Browse worktrees（浏览工作树），选中托管检出，再选择 Resume owner thread（恢复所属线程）。不要给 codex resume 追加 --worktree；恢复操作应该返回该会话已经绑定的检出，而不是再分配一份。

5. 清理检出前先保存改动

确定要保留的改动，应先在工作树中运行相关测试、完成提交，并复制提交 SHA。然后回到原检出，用 git cherry-pick <sha> 把该提交带入当前分支。务必先 cherry-pick，再移除工作树，确保 detached 提交已有持久归宿。

如果这批改动需要单独走评审流程，可在工作树中运行 git switch -c codex/<task>，随后提交、推送并创建 pull request。Git 不允许同一分支同时在原检出中签出。因此，要么直接从工作树推送，要么先移除工作树，再到其他位置签出该分支。

CLI 创建的工作树不会自动清理。确认改动已经安全提交或明确丢弃，并再次检查检出状态干净后，从源仓库运行 git worktree remove <worktree-path>。不要使用 --force。之后可用 git worktree prune 清除过期的 Git 登记，但它不能替代对会话是否仍占用该检出的检查。

这项功能如何影响成本

这项原生能力省掉了一小段却会反复出现的 shell 编排。0.154.0 之前，CLI 用户需要自行创建路径、创建分支或进入 detached 状态、在该目录启动 Codex、记住聊天与工作树的对应关系，最后还要分别清理 Git 和会话状态。现在，新参数可在一次启动中完成检出的创建与绑定，而 /worktree 提供了理解仓库上下文的浏览和恢复入口。

对于现有 Codex 订阅用户，这份检出没有单独公布的费用。Codex Plus 每月 $20。面向商业团队、用于组织并行工作树的 agent 工作区 Unstoppable，其付费 Pro 方案每月 $19 起，Business 为每位用户每月 $29，Enterprise 为每位用户每月 $49。若需求只是创建隔离检出并恢复会话，原生 Codex 现在已经能在现有订阅内完成这项窄任务。

但它并不能取代这类付费工作区的其他能力。跨 agent 看板、端口分配、共享环境初始化、测试汇总、pull request 跟踪、团队策略和成本报告，仍位于底层检出之上。并行会话也依然共享同一份 Codex 使用额度。因此，合理的成本判断不是“免费并行开发”，而是“如果购买编排工具只是为了隔离，现在可以少用一个工具”。

如果想了解这项功能所在的完整产品体验，可阅读 Codex 评测，其中介绍了本地 CLI 与 agent 工作流。此前的 Codex CLI 0.152.0 解析则说明了：自动化终端时，特定版本的限制为什么值得重视。

七类最值得使用工作树的任务

1. 高风险依赖升级

维护者可以为框架、包管理器或测试运行器升级启动独立工作树，让 Codex 修改 lockfile 和配置、运行完整测试套件，而不会弄脏主检出中正在进行的功能开发。收益是得到一条可审查的升级通道；如果结果不理想，无需 stash，也无需回滚无关改动，直接丢弃即可。

2. 为同一功能尝试不同实现

技术负责人可以把同一段规划对话分叉到两个托管工作树：一个会话尝试最小补丁，另一个采用更结构化的方案，再比较 diff 大小、测试结果和迁移风险。这样，第二次尝试不会覆盖第一次，最终选择也有证据支撑。

3. 在产品开发期间并行排查缺陷

产品工程师做到一半时，可以从已提交的 HEAD 新建干净工作树，用来复现生产环境缺陷。Codex 能在这条独立通道里加诊断、测试并修复问题，未完成的功能则留在原处。这样既减少紧急 stash，也能得到更干净的 hotfix diff。

4. 大规模 codemod 与重构

平台团队可以把大范围重命名或 API 迁移放入单独检出，在其中运行格式化和测试，等确认变更文件集合后再合入主分支。收益在于控制范围：自动生成的大量改动只有通过检查后才进入提交。

5. 独立处理评审修改

pull request 作者可以先提交评审基线，再从该状态启动隔离的 Codex 会话，逐条处理评审意见，不影响本地正在使用的其他分支。完成后可直接从工作树推送，形成一组聚焦的修正提交。

6. 可复现的维护任务

构建工程师可以用 codex exec --worktree 执行更新生成文件、排查不稳定测试等聚焦任务。无界面运行会获得干净的受跟踪文件检出，同时留下可供后续检查的持久会话。好处是避免受到主工作树当前内容的意外污染；前提是自动化流程必须自行负责依赖初始化和清理。

7. 安全熟悉陌生仓库

新成员可以先让 Codex 梳理陌生代码库，再在托管工作树里尝试小范围文档或测试修改，暂时不碰日常使用的检出。这份收益也体现在心理层面：探索有清晰边界，放弃成果同样简单。

围绕现有缺口，值得做的三款产品

1. 最值得押注：工作树就绪层

可以做一款轻量本地工具，把刚创建的托管检出变成可运行、不会争用资源的任务通道。它负责识别项目技术栈、执行获准的依赖初始化、分配端口、创建临时数据库或 schema、只暴露选定的密钥、完成健康检查，并输出配套清理方案。

需求面并不窄：git worktree 在美国 Google 每月约有 9,900 次搜索，what is a git worktree 还有 590 次。Codex 原生功能解决了检出创建，却没有补齐运行环境就绪流程，因此这是最值得投入的机会。

最小可售版本需要仓库 manifest、初始化与拆除命令、端口预留、环境文件模板和状态检查。真正的风险在安全侧：复制密钥或让两个 agent 指向同一个数据库，可能让工具带来的风险大于它解决的问题。OpenAI 也可能加入第一方生命周期 hook，进一步压缩这一缺口。

2. 跨 agent 任务通道看板

可以打造桌面端或终端看板，发现不同仓库、不同工具中的工作树，并集中展示所属会话、分支或 detached 状态、变更文件、测试结果、Codex 用量、pull request、磁盘占用，以及安全恢复或清理操作。

git worktree claude code 在美国每月约有 480 次搜索，完全匹配的 parallel coding agents 则有 10 次。后一个查询量虽小，但付费行为已经存在：包含并行 agent 工作树能力的 Unstoppable，起步价为每月 $19。目标用户正是已经在 Codex、Claude Code 和普通终端之间来回切换的开发者。

MVP 可以完全只读：枚举 Git 工作树、关联已知会话元数据、按需运行状态与测试命令，并提供返回各 agent 的深链接。需要注意原生功能的竞争：Codex 0.154.0 已能浏览自身管理的工作树，因此这款产品必须依靠跨 agent 可见性、运行时状态和团队报告取胜。

3. 集成与清理闸门

可以做一道位于已完成 agent 任务通道与主分支之间的防线。它检查工作区是否干净、运行规定测试、识别被其他活跃工作树修改的文件、建议 cherry-pick 顺序，并在仍有提交尚未集成时拒绝破坏性清理。

搜索需求已经直接反映出这些困惑：git remove worktree 在美国每月约有 390 次搜索，git worktree vs branch 为 320 次，git worktree prune 为 140 次。这些查询都集中在同一个节点：如何把隔离成果安全转化为共享成果。

MVP 可以是一条本地 Git 命令，加上一份小型策略文件；即使不自动修改任何代码，也能提供价值。难点在分发：Git 客户端和 CI 厂商都可以加入同类检查，因此独立工具必须在多种编码 agent 和真实世界的复杂仓库上表现出色。

哪些限制会影响是否采用 Codex worktree

当问题是文件隔离时，可以使用原生工作树；但不要把它误认为完整的环境隔离。

这个版本也没有与桌面应用 Handoff 按钮对应的 CLI 功能。把代码带回主线仍然是 Git 层面的决定：提交后 cherry-pick、推送分支，或直接丢弃并移除。这种明确步骤反而合理；隔离之所以有价值，正是因为任何改动都不该意外流入主检出。

本周一就做这件事：挑一次非关键依赖升级，用 codex --enable worktrees --worktree 运行；从复制出的检出路径检查 diff 和测试，只 cherry-pick 被接受的提交，然后移除工作树。如果你希望为自己的仓库搭建可靠的隔离 agent 工作流，我可以帮你设计生产级系统。