Codex Worktrees 怎么用:多任务并行不改乱本地文件与 Handoff 交接教程

在同一个代码仓库同时开两个 Codex 对话改需求,直接跑在本地目录(Local)极易互相覆盖文件。本文按 OpenAI Codex 官方文档讲清内置 Worktrees(Git 工作树)的创建步骤、起始分支选择、后台并行运行以及用 Handoff 把代码迁回本地的方法。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 Plus 账号

结论先说

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

Codex 本地检出与工作树模式对比

图:本站根据 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),而工作树解决的是多场独立对话同时改文件的物理隔离。

开启 Worktree 并交接回本地四步

图:本站根据 OpenAI Codex 官方文档 Worktrees 整理的示意图

二、四步上手创建工作树并用 Handoff 收口

第一步:在新建对话底部选择 Worktree

在桌面端选中你的 Git 仓库项目,开启新对话时,在底部输入框(Composer)下方将执行位置从 Local 切换为 Worktree。如果你的新工作树每次检出后都需要自动跑 pnpm install 或生成环境变量,可以顺手关联一份本地环境初始化脚本(Local Environment)。

第二步:选定起始基准分支

在输入框下方展开分支选择器,指定这份新副本以哪条分支为底子:既可以选干净的 main 主干,也可以选某个开发分支,甚至支持携带当前本地未暂存改动(Unstaged changes)直接拉起实验副本。

第三步:发出指令后台并行推进

发出提示词后,Codex 会自动在受管目录创建 Git 工作树并默认切入分离头指针状态开始读写代码和跑测试。值得一提的是,如果你在手机端 ChatGPT App 绑定了家里或工位在线的电脑,外出时也能在手机上直接发起、审批和审阅运行在那台电脑上的工作树对话(代码和命令依然留在你自己的电脑上运行,不会搬去手机本地)。

第四步:审阅满意后触发 Handoff(双向交接)

等后台工作树跑通测试、你在变更视图里确认代码靠谱后,有两个去向可选:

  1. 直接在工作树里让 Codex 建好新分支推远程提 PR;
  2. 点击 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 检查清理不再使用的旧目录,就能及时释放本地磁盘空间。

相关教程

参考资料

  • OpenAI Codex 官方文档:Worktrees — https://learn.chatgpt.com/docs/worktrees
  • OpenAI Codex 开发者中心 — https://developers.openai.com/codex

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  2. 02

    多 Agent 的成本为什么翻倍、怎么控制:Token 膨胀根源与五项降本措施

    刚把单智能体拆成多 Agent,用量往往暴涨好几倍。Anthropic 工程报告统计单智能体约为聊天的 4 倍 Token,多智能体可达约 15 倍。本文拆解固定前缀重复加载、历史搬运、工具链定义与缓存失效四大根源,并给出五条实操控费办法。

    ChatGPTClaude0
  3. 03

    多 Agent 协同开发怎么落地:「一个写、一个审」双代理工作流搭建指南

    多 Agent 协同开发里投入产出比最高的模式就是「一个写、一个审」。本文依据 Anthropic 与 OpenAI 官方编码最佳实践,讲清为什么同会话自审容易漏问题,以及用只读子代理、跨模型交叉审查(Claude Code + Codex)和自动化闭环落地的具体方法。

    ClaudeCodex0
  4. 04

    多 Agent 编排模式详解:编排者-工作者、交接(Handoffs)、并行与评估循环怎么选

    搜「multi-agent orchestration 中文」会被各家框架的不同术语绕晕。本文对照 Anthropic《Building effective agents》与 OpenAI 智能体指南,把编排者-工作者、去中心化交接、并行分片投票与生成-评估循环四种标准编排拓扑讲透。

    ChatGPTClaude0
  5. 05

    多智能体(Multi-Agent)是什么、什么时候该用:Anthropic 与 OpenAI 官方判断标准

    多智能体不是代理越多越聪明。本文依据 Anthropic 研究系统架构文章与 OpenAI 官方智能体指南,讲清确定性工作流、单智能体与多智能体的区别,以及哪三类瓶颈才值得上多智能体协同。

    ChatGPTClaude0
  6. 06

    codebase-memory 类 MCP 是什么、怎么用:基于语法树图谱的本地代码索引原理与配置

    codebase-memory-mcp(DeusData/codebase-memory-mcp)是一类本地代码图谱 MCP 服务器:用 Tree-sitter 把仓库解析成函数与调用关系的 SQLite 图库,帮编码助手查调用链并省下读整份文件的额度。

    ClaudeCodex0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~