结论先说
- Worktrees 的底层就是标准
git worktree:只有本身已经是 Git 仓库的项目才能开启(非 Git 普通文件夹只能直接跑在原目录,相关报错排查见 /guides/codex-cannot-use-project-for-local-chat)。 Local和Worktree的本质区别在于改谁的磁盘目录:选 Local 会直接修改你当前打开的项目文件夹;选 Worktree 会自动检出一份共享.git历史的独立目录副本,怎么折腾都不会弄脏你手头正编辑的文件。- 默认在分离头指针(Detached HEAD)下安全起步:创建时你可以任选
main、某个功能分支,甚至把当前未暂存改动带过去作为起点。 - 改完不用手工拷文件,直接点
Handoff(交接):官方内置了双向交接流程,能把「聊天上下文 + 代码改动」一次性安全搬回你的本地主目录继续调试提交。

图:本站根据 OpenAI Codex 官方文档 Worktrees 整理的示意图
本文根据 OpenAI Codex 官方文档《Worktrees》整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 搜「codex worktree 怎么用」「codex 同时跑多个任务不冲突」的开发者;
- 在本地编辑器写代码写到一半,想让 Codex 在后台顺手修另一个分支的缺陷,又怕它改动当前工作区文件或切走当前分支的人;
- 打开桌面端看到输入框底下有 Local 和 Worktree 两个选项,不知道选哪个以及改完后代码去哪找的同学。
如果你平时也在用 Claude Code 的命令行工作树,可以横向对照 /guides/claude-code-worktree;想分清桌面 App 与命令行的能力差异,见 /guides/codex-app-vs-cli-which-better。
一、什么时候用 Local、什么时候必须切 Worktree
很多人在桌面 App 里习惯一路默认到底,结果同时发起两条对话后,两边的测试和构建互相踩脚。按官方设计定位,可以把两者这样分工:
- 留在 Local(本地检出):你此刻就在 IDE 里盯着这一个需求,希望 Codex 每改完一行你立刻在 VS Code 里保存预览、刷新本地开发服务器看效果;
- 切到 Worktree(独立工作树):你手里正专注写主线功能,突然想到「顺便让 Codex 把上周那三个边缘单测补上」「试探性重构一下旧接口看看行不行」,或者配置了后台定时巡检任务——全部丢进独立工作树排队跑,前台零干扰。
注意区分它和「子代理(Subagents)」的差别:子代理解决的是同一场对话内部派几个助手分头查代码(见 /guides/codex-multi-agent-subagents-guide),而工作树解决的是多场独立对话同时改文件的物理隔离。

图:本站根据 OpenAI Codex 官方文档 Worktrees 整理的示意图
二、四步上手创建工作树并用 Handoff 收口
第一步:在新建对话底部选择 Worktree
在桌面端选中你的 Git 仓库项目,开启新对话时,在底部输入框(Composer)下方将执行位置从 Local 切换为 Worktree。如果你的新工作树每次检出后都需要自动跑 pnpm install 或生成环境变量,可以顺手关联一份本地环境初始化脚本(Local Environment)。
第二步:选定起始基准分支
在输入框下方展开分支选择器,指定这份新副本以哪条分支为底子:既可以选干净的 main 主干,也可以选某个开发分支,甚至支持携带当前本地未暂存改动(Unstaged changes)直接拉起实验副本。
第三步:发出指令后台并行推进
发出提示词后,Codex 会自动在受管目录创建 Git 工作树并默认切入分离头指针状态开始读写代码和跑测试。值得一提的是,如果你在手机端 ChatGPT App 绑定了家里或工位在线的电脑,外出时也能在手机上直接发起、审批和审阅运行在那台电脑上的工作树对话(代码和命令依然留在你自己的电脑上运行,不会搬去手机本地)。
第四步:审阅满意后触发 Handoff(双向交接)
等后台工作树跑通测试、你在变更视图里确认代码靠谱后,有两个去向可选:
- 直接在工作树里让 Codex 建好新分支推远程提 PR;
- 点击 Handoff(交接) 把这场对话连同代码变更安全迁回你的 Local 本地检出目录(同理,你在 Local 改了一半临时要腾出主目录修线上急单时,也能用 Handoff 把半成品挪进 Worktree 挂起)。
由于多开三四个工作树并行跑复杂重构会同时消耗账号的滚动周期配额,高频并行研发者若经常触及 Plus 窗口限制,可参考 /chongzhi/chatgpt-pro 或 /chongzhi/chatgpt-plus 对照不同官方套餐的并发与额度上限。
常见问题
Q:交接(Handoff)回 Local 时,如果我本地主目录正好也有未提交的冲突改动怎么办?
Codex 在执行 Handoff 前会自动检查两边的 Git 工作区状态。为了避免合并冲突阻塞交接,最干净的习惯是在把后台工作树迁回 Local 之前,先把主目录手头改完的内容做一次正常 git commit 或 git stash。
Q:用完的大量旧工作树副本会一直占满电脑硬盘吗?
每个工作树都会在磁盘检出一份源码(如果装了独立 node_modules 体积更大)。对于已经合并上线或废弃的实验会话,归档删除对应工作树对话或定期用 git worktree list 检查清理不再使用的旧目录,就能及时释放本地磁盘空间。
相关教程
- /guides/codex-app-vs-cli-which-better:Codex 桌面 App 与 CLI 命令行全面对比
- /guides/codex-multi-agent-subagents-guide:Codex 子代理(Subagents)并行分工配置指南
- /guides/codex-cannot-use-project-for-local-chat:Codex 本地项目目录报错与 Git 初始化排查
- /guides/claude-code-worktree:Claude Code
worktree并行开发用法对比
参考资料
- OpenAI Codex 官方文档:Worktrees — https://learn.chatgpt.com/docs/worktrees
- OpenAI Codex 开发者中心 — https://developers.openai.com/codex
0 条评论
还没有评论,来抢沙发~