結論先說
- 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 條評論
還沒有評論,來搶沙發~