Codex 中文手冊

繁體中文

简体中文

繁體中文

简体中文

外觀

交流群即將上線

工作樹 ​

本頁是 OpenAI 官方文件 的中文鏡像，譯文由官方維護。以官方頁面為準。

工作樹可讓 Codex 在同一個專案中執行多個彼此獨立的對話，且互不干擾。程式碼庫、工作樹和指令都會保留在包含該專案的電腦或遠端開發環境中。你可以直接使用 ChatGPT 桌面版應用程式，或透過 ChatGPT 行動版應用程式中的遠端功能，在已連線的電腦上開始、引導、核准及審查工作樹對話。

對於 Git 程式碼庫，排程任務可在專用的背景工作樹上執行，避免與進行中的工作衝突。在未納入版本控制的專案中，排程任務會直接在專案目錄中執行。你也可以手動在工作樹中開始對話，並透過移交功能在本機與工作樹之間移動對話。

工作樹不會在手機本機執行。使用遠端功能時，行動版應用程式會控制已連線電腦上的 Codex；程式碼庫與工作樹仍保留在該電腦，或該電腦使用的遠端開發環境中。以下桌面版專用操作說明適用於已連線的電腦。

什麼是工作樹 ​

工作樹僅適用於屬於 Git 程式碼庫的專案，因為其底層採用Git 工作樹。工作樹可讓你建立程式碼庫的第二份副本，也就是「簽出」。每個工作樹都有程式碼庫中所有檔案各自的副本，但所有工作樹共用提交、分支等相关中繼資料（.git 資料夾）。因此，你可以簽出多個分支並平行作業。

術語 ​

  • 本機簽出：你建立的程式碼庫。在 ChatGPT 桌面版應用程式中，有時簡稱為 本機 。
  • 工作樹：在 ChatGPT 桌面版應用程式中，從本機簽出建立的Git 工作樹。
  • 移交：在本機與工作樹之間移動對話的流程。Codex 會處理必要的 Git 作業，確保你的工作能安全地在兩者之間移動。

為什麼要使用工作樹 ​

  1. 與 Codex 平行處理工作，而不影響目前的本機設定。
  2. 將背景工作排入佇列，同時專注於前景工作。
  3. 等你準備好進行更直接的檢查、測試或協作時，再將對話移至本機。

開始使用 ​

工作樹需要 Git 程式碼庫。請確認你選取的專案位於 Git 程式碼庫中。

  1. 選取「工作樹」

    在新增對話檢視畫面中，選取撰寫工具下方的 工作樹 。 你也可以視需要選擇本機環境，為工作樹執行設定指令碼。

  2. 選取起始分支

    在撰寫工具下方，選擇建立工作樹所依據的 Git 分支。你可以選擇 main / master 分支、功能分支，或目前有未暫存本機變更的分支。

  3. 送出提示詞

    送出提示詞後，Codex 會根據所選分支建立 Git 工作樹。依預設，Codex 會在「分離的 HEAD」狀態下作業。

  4. 選擇繼續作業的位置

    準備好後，你可以直接在工作樹上繼續作業，或將對話移交至本機簽出。將對話移交至本機或從本機移交出去時，會同時移動對話 與 程式碼，讓你能在另一個簽出中繼續作業。

在本機與工作樹之間作業 ​

工作樹的外觀與操作體驗和本機簽出十分相似，差別在於兩者在工作流程中的定位。你可以把本機視為前景，將工作樹視為背景。移交功能可讓你在兩者之間移動對話。

移交功能會在底層處理必要的 Git 作業，以便在兩個簽出之間安全地移動工作。這一點十分重要，因為 Git 一次只允許在一個位置簽出同一個分支。如果你在工作樹上簽出某個分支，就 無法 同時在本機簽出中簽出該分支，反之亦然。

實務上，常見做法有兩種：

  1. 只在工作樹上作業。如果你能直接在工作樹上驗證變更，例如已透過本機環境設定指令碼安裝相依項目與工具，這種做法最合適。
  2. 將對話移交至本機。如果你想將對話移到前景，例如在常用的 IDE 中檢查變更，或應用程式一次只能執行一個執行個體，請採用這種做法。

選項 1：在工作樹上作業 ​

如果你只想在工作樹上處理變更，請使用對話標頭中的 在此建立分支 按鈕，將工作樹轉為分支。

接著，你可以提交變更、將分支推送至遠端程式碼庫，並在 GitHub 上開啟 Pull Request。

你可以使用標頭中的「開啟」按鈕，在 IDE 中開啟工作樹；也可以使用整合式終端，或從工作樹目錄執行其他所需操作。

請注意，如果你在工作樹上建立分支，就無法在任何其他工作樹中簽出該分支，包括本機簽出。

選項 2：將對話移交至本機 ​

如果你想將對話移到前景，請在對話標頭中選取 移交 ，並將對話移至 本機。

如果你想在常用的 IDE 視窗中查看變更、執行現有的開發伺服器，或在日常使用的相同環境中驗證工作，這種做法很適合。

Codex 會處理必要的 Git 步驟，確保對話能安全地在工作樹與本機簽出之間移動。

每個對話都會持續與同一個工作樹保持關聯。日後如果將對話移交回工作樹，Codex 會將其送回相同的背景環境，讓你接續先前的進度。

你也可以反向操作。如果你已在本機作業，並想騰出前景，請使用 移交 將對話移至工作樹。當你想讓 Codex 在背景繼續作業，同時將注意力轉回本機上的其他工作時，這項功能很實用。

由於移交功能使用 Git 作業，任何列在 .gitignore 檔案中的檔案都不會隨對話移動，除非 Codex 使用 .worktreeinclude 將這些檔案複製到本機受管理的工作樹中。

進階資訊 ​

Codex 管理的工作樹與永久工作樹 ​

依預設，對話會使用 Codex 管理的工作樹。這類工作樹設計為輕量且可隨時捨棄。Codex 管理的工作樹通常專供單一對話使用；如果你稍後將對話移交回工作樹，Codex 會將它送回同一個工作樹。

如需長期使用的環境，請透過側邊欄中專案的三點選單建立永久工作樹。這會建立新的永久工作樹，並將其作為獨立專案。永久工作樹不會自動刪除，而且你可以在同一個工作樹中開始多個對話。

Codex 如何為你管理工作樹 ​

Codex 會在 $CODEX_HOME/worktrees 中建立工作樹。起始提交是開始對話時所選分支的 HEAD 提交。如果選擇的分支有本機變更，Codex 也會將未提交的變更套用至工作樹。工作樹不會簽出為分支，而是處於分離的 HEAD 狀態。如此一來，Codex 可以建立多個工作樹，而不會讓你的分支變得雜亂。

將已忽略的本機檔案複製到受管理的工作樹 ​

本機上由 Codex 管理的工作樹以 Git 簽出為起點，因此已包含受追蹤的檔案。如果程式碼庫忽略了新工作樹所需的本機設定檔案，請在程式碼庫根目錄新增 .worktreeinclude 檔案，並列出要複製的已忽略路徑或 .gitignore 格式的比對模式，以便 Codex 建立受管理工作樹時一併複製。

此功能適用於刻意讓 Git 忽略的檔案，例如 .env、.env.local 或 config/secrets.json。Codex 只會複製符合 .worktreeinclude 的已忽略檔案，不會複製 Git 未追蹤的其他本機檔案。請勿列出受追蹤的檔案。

Codex 會自動將已忽略的 AGENTS.override.md 複製到本機受管理的工作樹，因此不需要在 .worktreeinclude 中列出該檔案。

text
# .worktreeinclude
.env
.env.local
config/secrets.json

Codex 會略過來源中的符號連結，也不會覆寫新簽出中已存在的檔案。這項行為適用於 ChatGPT 桌面版應用程式在本機管理的工作樹，不適用於遠端工作樹，也不適用於你自行透過指令列建立的 Git 工作樹。

分支限制 ​

假設 Codex 在工作樹上完成部分工作後，你選擇透過 在此建立分支在該工作樹上建立 feature/a 分支。現在，你想在本機簽出中試用這個分支。如果嘗試簽出該分支，就會收到以下錯誤：

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

若要解決此問題，你必須在工作樹上改為簽出另一個分支，而不是 feature/a。

如果打算在本機簽出該分支，請使用移交功能將對話移至本機，而不要嘗試在兩個位置同時簽出同一個分支。

Git 不允許同一個分支同時在多個工作樹中簽出，因為分支代表單一可變參照（refs/heads/<name>），表示工作樹的「目前簽出狀態」。

簽出分支時，Git 會將其 HEAD 視為該工作樹專有，並預期提交、重設、變基和合併等操作會依照明確順序更新該參照。如果允許多個工作樹同時簽出相同分支，便無法明確判定應由哪個工作樹的操作更新分支參照，並會產生競爭條件，可能導致提交遺失、索引不一致，或衝突解決方式不明。

Git 規定每個分支只能由一個工作樹簽出，以確保各分支都有唯一且具權威性的工作副本，同時允許其他工作樹透過分離的 HEAD 或其他分支，安全地參照相同的提交。

工作樹清理 ​

工作樹可能會占用大量磁碟空間。每個工作樹都有各自的程式碼庫檔案、相依套件、建置快取等。因此，ChatGPT 桌面版應用程式會盡量將工作樹數量維持在合理範圍內。

Codex 預設會保留最近的 15 個由 Codex 管理的工作樹。如果您偏好自行管理磁碟用量，可以在設定中變更此上限，或關閉自動刪除功能。

Codex 會盡量避免刪除仍然重要的工作樹。若符合下列情況，由 Codex 管理的工作樹不會自動刪除：

  • 有已釘選的對話與該工作樹關聯
  • 對話仍在進行中
  • 該工作樹是永久工作樹

由 Codex 管理的工作樹會在下列情況下自動刪除：

  • 您封存與該工作樹關聯的對話
  • Codex 需要刪除較舊的工作樹，才能將數量維持在您設定的上限內

刪除由 Codex 管理的工作樹前，Codex 會儲存其中工作內容的快照。如果您在工作樹刪除後開啟與其關聯的對話，便會看到還原該工作樹的選項。

常見問題 ​

可以。Codex 預設會在 $CODEX_HOME/worktrees 下建立 由 Codex 管理的工作樹。若要選擇其他位置，請開啟 設定 > 工作樹 ，並變更 工作樹根目錄。

可以。請使用對話標頭中的 移交 功能，在本機 簽出目錄與工作樹之間移動對話。Codex 會執行必要的 Git 操作，確保 對話能在不同環境之間安全移動。如果您日後將對話移交回工作樹， Codex 會將其移回原先關聯的工作樹。

即使底層工作樹目錄遭到刪除，對話仍可保留在您的 对話記錄中。對於由 Codex 管理的工作樹，Codex 會在刪除前 儲存快照；如果您重新開啟相關聯的對話，Codex 會提供還原工作樹的選項。 封存與永久工作樹關聯的對話時， 該工作樹不會自動遭到刪除。

非官方社群教程 · 「官方文件」區為 learn.chatgpt.com 中文原文映象 · 以官方頁面為準

Copyright © 2026 Codex 中文手冊