一、为什么需要 Worktree / Cloud？

前面几篇我们基本都在讲一个任务：

打开项目 → 给 Codex 一个任务 → 它修改文件 → 你验收结果

这适合新手入门。

但真实开发里，你经常会同时面对多个事情：

• 你正在本地改一个页面
• 另一个 Bug 可以让 Codex 先排查
• 测试覆盖率不够，可以让 Codex 后台补
• README 和变更说明可以让 Codex 写
• 某个 PR 可以让 Codex 在云端跑完再给你看

如果这些任务都挤在同一个本地目录里，就容易乱：

你改了一半的文件 Codex 又改同一批文件 测试跑不清楚是谁导致失败 Diff 里混着你的改动和 Codex 的改动 最后不知道该保留什么

Worktree 和 Cloud 的意义，就是把任务隔离开。

二、先理解三种模式：Local、Worktree、Cloud

Codex App 里常见的三种工作模式可以这样理解：

模式	简单理解	适合场景
Local	直接在你当前项目目录工作	你正在盯着改动、需要本地调试和验证
Worktree	在本机创建一个独立 Git worktree	并行任务、后台实验、不想污染当前工作区
Cloud	在远程环境里运行任务	长任务、PR、远程并行、离开电脑也能跑

Local：前台工作区

Local 就是你当前的项目目录。

适合：

• 你正在调试页面
• 需要复用本地开发服务器
• 需要打开 IDE 逐行看代码
• 需要和 Codex 来回改一个具体问题

缺点也很明显：Codex 的改动会直接进入你的当前工作区。

如果你自己也正在改同一批文件，就容易冲突。

Worktree：本机后台工作区

Worktree 基于 Git worktree。你可以把它理解成同一个仓库的“第二份 checkout”。

Codex 在这个独立目录里工作，你的本地目录继续保持原样。

适合：

• 让 Codex 后台补测试
• 让 Codex 尝试一个重构方案
• 同时跑两个互不相关的小任务
• 你想保留当前本地工作区不被打扰

官方文档里也强调，Worktree 适合让 Codex 在同一项目里跑多个独立任务，而不干扰你的 Local。

Cloud：远程工作区

Cloud 是远程任务。

它会在云端环境里 checkout 你的仓库，运行 setup，执行任务，然后展示结果和 diff。你可以后续继续追问、生成 PR，或者把结果拉回本地。

适合：

• 比较长的任务
• 不想占用本机资源
• 需要远程持续运行
• 连接 GitHub 后生成 PR
• 你离开电脑也希望任务继续推进

注意：Cloud 不是本地 worktree。它需要配置环境，通常要连接 GitHub 仓库，还要考虑 setup script、依赖、环境变量和 secrets。

三、什么时候用 Worktree？

一句话：

你还在本地开发，但想让 Codex 在旁边独立做另一件事，就用 Worktree。

典型场景：

场景 1：你在改页面，让 Codex 补测试

你正在 Local 里调试首页布局。

同时你可以让 Codex 在 Worktree 里做：

Create a separate background thread in a worktree for this project to add tests for the date utilities. Scope: 1. Only modify test files and date utility files if necessary. 2. Do not touch page components. 3. Run the relevant test command. 4. Report changed files and test results.

这样你本地页面开发不受影响。

场景 2：让 Codex 尝试一个方案，但你不确定要不要

比如你想重构组件，但不确定方案是否靠谱。

Create a separate worktree thread to prototype a refactor of the FilterPanel component. Requirements: 1. Keep behavior unchanged. 2. Do not modify API calls. 3. Run relevant tests if available. 4. Do not merge into Local until I review the diff.

这个任务如果做坏了，不会直接污染你的当前工作区。

场景 3：同时比较两个实现方案

比如同一个功能，你想看两个方案：

• 方案 A：保守改造
• 方案 B：组件抽象

可以开两个 Worktree 线程，各自跑。

但注意：这种并行只适合低耦合任务。如果两个方案都要改同一批核心文件，后面合并会很痛苦。

四、Worktree 的正确使用流程

官方文档里提到，Worktree 需要 Git 仓库，因为底层用的是 Git worktree。

所以第一步是确认你的项目是 Git 仓库：

git status

如果不是，先初始化：

git init

推荐流程：

1. 当前项目保持在 Local 2. 新建一个 Codex thread 3. 选择 Worktree 4. 选择起始分支 5. 输入明确任务 6. Codex 在独立 worktree 中工作 7. 查看结果和 Diff 8. 需要时 Handoff 到 Local

在 Codex App 中，新建 thread 时可以选择 Worktree。它会基于你选择的分支创建独立工作区。官方文档提到，Codex 管理的 worktree 默认通常是 detached HEAD 状态，这样可以避免污染你的分支。

这点很好理解：

Local 是你手上的主工作台 Worktree 是旁边临时开出来的一张桌子

五、Handoff：什么时候把 Worktree 移回 Local？

Worktree 做完不等于任务完成。

你还要验收。

官方文档里提到，Handoff 可以把 thread 和代码在 Local 与 Worktree 之间移动。这个过程由 Codex 处理底层 Git 操作。

适合 Handoff 到 Local 的情况：

• 你要用本地 IDE 细看代码
• 你只能在 Local 跑开发服务器
• 你要用当前本地环境做手动验证
• 你准备接手这个改动继续开发

不一定要 Handoff 的情况：

• 任务很独立
• Worktree 里已经能跑测试
• 你打算直接在 worktree 上建分支、提交、推送

注意一个 Git 限制：同一个分支不能同时被多个 worktree checkout。如果你在 worktree 里创建了一个分支，再想在 Local checkout 同一个分支，可能会遇到分支被另一个 worktree 占用的问题。

遇到这种情况，优先考虑 Handoff，而不是强行 checkout。

六、什么时候用 Cloud？

一句话：

任务可以远程跑、可以基于 GitHub 仓库工作、你不想占用本地环境，就用 Cloud。

Cloud 更适合：

• 跑长任务
• 生成 PR
• 批量处理 TODO
• 修 CI
• 在你离开电脑时继续推进
• 团队协作中让 Codex 处理远程分支

Codex Web / Cloud 通常需要连接 GitHub 仓库。官方文档里也提到，可以去 ​编辑Codex 连接 GitHub，让 Codex 使用仓库代码并从结果创建 PR。

七、Cloud 任务是怎么跑的？

Cloud 不是魔法。它有一个明确生命周期。

根据官方文档，Cloud 任务大致是：

1. 创建容器 2. checkout 你的 repo 到指定分支或 commit 3. 运行 setup script 4. 应用网络访问设置 5. Agent 执行任务：读代码、改文件、跑检查 6. 完成后展示回答和 diff 7. 你可以继续追问、打开 PR 或处理结果

这里有几个关键点。

1. setup script 很重要

Cloud 环境不是你的本机。

如果项目依赖复杂，你要告诉 Cloud 怎么准备环境。

例如：

pnpm install pnpm build

或者：

poetry install --with test pnpm install

否则 Codex 可能无法运行测试或构建。

2. secrets 和环境变量要分清

官方文档里提到：

• 环境变量可以在任务期间使用
• secrets 会更安全地存储，但只在 setup 阶段可用，agent 阶段会被移除

所以不要假设 Cloud Agent 阶段能拿到所有 secrets。

3. Agent 阶段默认网络访问关闭

官方文档提到，setup 阶段可以联网安装依赖；agent 阶段默认关闭互联网访问，除非你配置允许。

这对安全是好事，但也意味着：

如果任务需要在线查文档、拉依赖、访问外部服务，你要提前配置环境和网络策略。

八、CLI 里也可以启动 Cloud 任务

如果你习惯终端，官方文档里也有 codex cloud 命令。

交互式浏览 Cloud 任务：

codex cloud

直接提交任务：

codex cloud exec --env ENV_ID "Summarize open bugs"

还可以用 --attempts 请求多个尝试：

codex cloud exec --env ENV_ID --attempts 3 "Propose fixes for the failing tests"

这里的 ENV_ID 来自你的 Codex Cloud 环境配置。

新手不必一开始就用 CLI Cloud。先在 Web / App 里把环境配置跑通，再考虑命令行自动化。

九、如何拆分并行任务？

并行不是越多越好。

真正的问题是：哪些任务能并行，哪些任务不能并行。

我建议用一个简单判断：

会不会改同一批文件？ 会不会改同一条业务链路？ 能不能独立验证？

适合并行的任务

这些任务通常可以放到 Worktree 或 Cloud：

任务	原因
补某个工具函数的测试	文件范围小，验证清楚
写 README / 文档	通常不影响代码
修独立页面 Bug	与主线开发冲突少
做一次代码解释 / 调研	不一定需要改文件
生成迁移计划	可先只输出方案

谨慎并行的任务

这些任务可以并行，但要小心：

任务	风险
改公共组件	多个页面可能依赖
改样式系统	容易影响全局 UI
改 hooks / utils	调用方很多
重构 API client	可能牵动业务逻辑

不建议并行的任务

这些任务最好不要多个线程同时搞：

任务	原因
认证 / 权限	高风险，验证复杂
支付 / 账单	业务风险高
数据库迁移	需要强一致性
大规模重构	合并冲突和行为风险都高
同一文件的两个方案	后面必然冲突

一句话：

文件范围越独立，越适合并行；业务链路越核心，越应该串行。

十、一个真实的并行工作流示例

假设你正在做一个管理后台。

你本地正在改：

首页数据看板

同时还有三个任务：

1. 修复设置页保存 Bug 2. 给日期工具函数补测试 3. 更新 README 的运行说明

推荐安排：

任务	模式
首页数据看板	Local
设置页保存 Bug	Worktree
日期工具函数测试	Worktree
README 更新	Cloud 或 Worktree

Local 继续做你手头的首页。

Worktree 线程 1：

Create a separate background thread in a worktree to fix the settings save bug. Bug: After clicking Save on /settings, the UI shows success but data is lost after refresh. Constraints: 1. Do not change API shape. 2. Keep the fix minimal. 3. Add a regression test if feasible. 4. Report changed files and test results.

Worktree 线程 2：

Create a separate background thread in a worktree to add tests for date utilities. Scope: 1. Focus on src/utils/date.ts and its tests. 2. Do not modify page components. 3. Cover valid dates, empty input, invalid date, and timezone edge cases. 4. Run the relevant test command.

Cloud 任务：

Run this in Codex Cloud. Task: Update README with accurate local setup and test commands. Requirements: 1. Read package.json before writing commands. 2. Do not invent unsupported scripts. 3. If a command is unclear, mark it as "to be confirmed". 4. Open a PR with the documentation change.

这样三个任务互不干扰。

十一、可复制的并行任务 Prompt

1. Worktree 后台修 Bug

Create a separate background thread in a worktree for this project. Task: Fix {Bug 描述}. Constraints: 1. Keep the fix minimal. 2. Do not change API request or response shapes. 3. Do not touch unrelated files. 4. Add or update a regression test if feasible. Verification: 1. Reproduce the bug if possible. 2. Run the smallest relevant test suite. 3. Report changed files, commands run, and remaining risks.

2. Worktree 后台补测试

Create a separate background thread in a worktree to add tests. Scope: 1. Target file: {文件路径} 2. Reference existing tests under {测试目录} 3. Cover happy path and edge cases. 4. Do not modify production code unless necessary; if necessary, explain why. Done when: Relevant tests pass and final response lists changed files.

3. Cloud 长任务

Run this in Codex Cloud on {branch}. Task: {任务描述} Requirements: 1. Follow AGENTS.md. 2. Run setup and relevant checks. 3. Keep the diff focused. 4. When finished, summarize changed files and validation results. 5. If checks cannot run, explain why.

4. 本地前台任务

Work in Local. Task: {当前前台任务} Constraints: 1. Do not touch files that background worktree tasks are modifying. 2. Keep changes focused. 3. Run local verification before final response.

十二、Worktree / Cloud 常见坑

坑 1：项目不是 Git 仓库

Worktree 需要 Git 仓库。

先检查：

git status

不是仓库就先：

git init

坑 2：两个线程改同一个文件

这是最常见的并行失败原因。

比如：

线程 A 改 src/components/Table.tsx 线程 B 也改 src/components/Table.tsx

最后你大概率要手动解决冲突。

拆任务前先看文件范围：

这个任务会改哪些文件？ 和我当前本地任务是否重叠？

坑 3：Worktree 缺少 .env 或本地配置

Codex-managed worktree 从 Git checkout 开始。

如果你的 .env.local 被 .gitignore 忽略，worktree 里可能没有。

官方文档提到，可以通过 .worktreeinclude 指定要复制的 ignored 文件，例如：

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

但这里要谨慎：不要随便复制敏感文件。只复制任务确实需要的本地配置。

坑 4：Cloud 环境没配好

本地能跑，不代表 Cloud 能跑。

Cloud 要靠 setup script 安装依赖和工具。

如果任务失败，先看：

setup script 是否正确？ Node / Python / pnpm 版本是否匹配？ 环境变量是否配置？ secrets 是否只在 setup 阶段可用？ Agent 阶段是否需要网络？

坑 5：分支被 worktree 占用

Git 不允许同一个分支同时被多个 worktree checkout。

如果你在 worktree 上创建了分支，再到 Local checkout 同名分支，可能会报错。

这时优先考虑：

Handoff 到 Local 或者让 worktree 切换/释放分支

不要粗暴删除你还没验收的 worktree。

坑 6：不看 Diff 就合并

Codex 说完成，不代表你应该直接接受。

合并前至少看：

git status git diff

在 Codex App 里，看 Review pane，尤其是：

• Last turn changes
• Uncommitted changes
• 是否有无关文件
• 测试和构建是否跑过
• 有没有 skipped checks

十三、并行任务的验收清单

并行任务完成后，按这个清单验收。

任务边界： [ ] 是否只改了指定范围？ [ ] 是否有无关文件变化？ [ ] 是否和 Local 当前改动冲突？ 验证： [ ] 是否运行相关测试？ [ ] 是否运行构建或 lint？ [ ] 失败项是否解释清楚？ 代码质量： [ ] 是否引入新依赖？ [ ] 是否改了 API 形状？ [ ] 是否动了认证/权限/支付等高风险逻辑？ 合并准备： [ ] 是否看过 Diff？ [ ] 是否需要 Handoff 到 Local？ [ ] 是否需要创建分支或 PR？ [ ] 是否可以安全删除/归档该 worktree？

可以把这段写进你的 AGENTS.md：

## Parallel task rules - Prefer Worktree for background tasks. - Do not run two parallel tasks that modify the same files. - Before final response, list changed files and verification commands. - If a task was done in a worktree, explain whether it should be handed off to Local or kept on the worktree. - If checks were skipped, explain why.

十四、Worktree、Cloud 和 AGENTS.md 怎么配合？

第 4 篇我们讲过 AGENTS.md。

到了 Worktree / Cloud 场景，它更重要。

因为你的任务会分散到不同环境：

Local 一个线程 Worktree 两个线程 Cloud 一个任务

如果没有统一规则，每个线程都可能按自己的理解做。

建议在 AGENTS.md 里写：

## Task isolation - Keep changes focused and avoid unrelated refactors. - Do not modify files outside the requested scope. - If a task may conflict with another active task, stop and ask. - Always list changed files in final response. ## Verification - Run the smallest relevant test suite. - Run build after frontend changes. - If checks cannot run in the current environment, explain why. ## Worktree / Cloud - For worktree tasks, explain whether Handoff to Local is recommended. - For cloud tasks, summarize setup issues, check results, and PR readiness.

这样每个环境里的 Codex 都会更接近同一套协作方式。

十五、什么时候不要并行？

不要为了并行而并行。

下面这些情况，建议串行：

1. 任务边界不清楚

如果你自己都不知道会改哪些文件，不要同时开多个线程。

先让 Codex 做分析：

请先分析这个任务可能涉及哪些文件。 只输出计划，不要修改。

2. 核心链路改造

比如：

• 登录
• 权限
• 支付
• 数据库 schema
• 订单状态机

这些最好串行推进，每一步都 Review。

3. 同一模块大重构

如果两个线程都要改公共组件或全局状态管理，冲突概率很高。

4. 你没有时间验收

并行任务越多，验收成本越高。

如果你没时间看 Diff，就不要一口气开 5 个任务。否则你只是把混乱推迟到了合并阶段。

十六、推荐实战路线

如果你刚开始用 Worktree / Cloud，建议按这个路线练：

阶段	练习任务	推荐模式
第 1 步	本地做一个小 UI 修改	Local
第 2 步	后台补一个工具函数测试	Worktree
第 3 步	后台修一个独立 Bug	Worktree
第 4 步	Handoff 回 Local 验收	Worktree → Local
第 5 步	Cloud 更新 README 或小 PR	Cloud
第 6 步	Cloud 修 CI 或批量 TODO	Cloud
第 7 步	把并行规则写进 AGENTS.md	项目规则

不要一开始就把所有任务扔到 Cloud。

先在 Worktree 里理解隔离和验收，再上 Cloud。

十七、总结

这篇的核心不是“Codex 能同时跑很多任务”，而是：

你能不能把任务拆得足够独立 能不能把环境准备好 能不能在合并前验收清楚

Local、Worktree、Cloud 的正确分工是：

Local：当前前台开发 Worktree：本机后台并行 Cloud：远程长任务和 PR

真正稳定的并行工作流应该是：

拆任务 → 选模式 → 明确范围 → 独立执行 → Review → 验收 → 合并

如果只记住一句话：

并行不是让 Codex 同时乱跑，而是让多个小而独立的任务在隔离环境里推进，最后由你统一验收。