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 條評論

登入 後參與評論

還沒有評論,來搶沙發~