一、为什么需要 Worktree / Cloud前面几篇我们基本都在讲一个任务打开项目 → 给 Codex 一个任务 → 它修改文件 → 你验收结果这适合新手入门。但真实开发里你经常会同时面对多个事情你正在本地改一个页面另一个 Bug 可以让 Codex 先排查测试覆盖率不够可以让 Codex 后台补README 和变更说明可以让 Codex 写某个 PR 可以让 Codex 在云端跑完再给你看如果这些任务都挤在同一个本地目录里就容易乱你改了一半的文件 Codex 又改同一批文件 测试跑不清楚是谁导致失败 Diff 里混着你的改动和 Codex 的改动 最后不知道该保留什么Worktree 和 Cloud 的意义就是把任务隔离开。二、先理解三种模式Local、Worktree、CloudCodex 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 移回 LocalWorktree 做完不等于任务完成。你还要验收。官方文档里提到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设置页保存 BugWorktree日期工具函数测试WorktreeREADME 更新Cloud 或 WorktreeLocal 继续做你手头的首页。Worktree 线程 1Create 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 线程 2Create 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.这样三个任务互不干扰。十一、可复制的并行任务 Prompt1. Worktree 后台修 BugCreate 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最后你大概率要手动解决冲突。拆任务前先看文件范围这个任务会改哪些文件 和我当前本地任务是否重叠坑 3Worktree 缺少 .env 或本地配置Codex-managed worktree 从 Git checkout 开始。如果你的 .env.local 被 .gitignore 忽略worktree 里可能没有。官方文档提到可以通过 .worktreeinclude 指定要复制的 ignored 文件例如# .worktreeinclude .env .env.local config/secrets.json但这里要谨慎不要随便复制敏感文件。只复制任务确实需要的本地配置。坑 4Cloud 环境没配好本地能跑不代表 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 changesUncommitted 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 步后台修一个独立 BugWorktree第 4 步Handoff 回 Local 验收Worktree → Local第 5 步Cloud 更新 README 或小 PRCloud第 6 步Cloud 修 CI 或批量 TODOCloud第 7 步把并行规则写进 AGENTS.md项目规则不要一开始就把所有任务扔到 Cloud。先在 Worktree 里理解隔离和验收再上 Cloud。十七、总结这篇的核心不是“Codex 能同时跑很多任务”而是你能不能把任务拆得足够独立 能不能把环境准备好 能不能在合并前验收清楚Local、Worktree、Cloud 的正确分工是Local当前前台开发 Worktree本机后台并行 Cloud远程长任务和 PR真正稳定的并行工作流应该是拆任务 → 选模式 → 明确范围 → 独立执行 → Review → 验收 → 合并如果只记住一句话并行不是让 Codex 同时乱跑而是让多个小而独立的任务在隔离环境里推进最后由你统一验收。