> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 受管理的工作樹

受管理的 worktree 會為代理程式任務提供專屬的 git 分支與簽出，而不會在原始碼儲存庫內放置暫存目錄。OpenClaw 會在其狀態目錄下建立這些 worktree、將它們記錄於共用狀態資料庫中，並在移除前快照保存其中已追蹤與未被忽略的未追蹤內容。

## 配置與名稱

每個 worktree 位於：

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
<openclaw-state-dir>/worktrees/<repo-fingerprint>/<name>
```

儲存庫指紋是針對正規化 git 共用目錄與來源 URL 計算 SHA-256 雜湊後，取其前 16 個十六進位字元。提供的名稱必須符合 `[a-z0-9][a-z0-9-]{0,63}`。若未提供名稱，OpenClaw 會產生 `wt-`，後接八個隨機十六進位字元。

OpenClaw 會在要求的基準參照建立分支 `openclaw/<name>`。若未提供基準參照，它會擷取 `origin`、在可用時使用遠端預設分支，並在儲存庫離線或沒有可用遠端時退回使用本機 `HEAD`。

## 佈建被忽略的檔案

在原始碼儲存庫根目錄新增 `.worktreeinclude`，即可將選定的已忽略未追蹤檔案複製到新的 worktree。此檔案使用 gitignore 模式語法，每行一個模式，並使用 `#` 註解：

```gitignore theme={"theme":{"light":"min-light","dark":"min-dark"}}
.env.local
fixtures/generated/**
```

只有 git 回報為同時已忽略且未追蹤的檔案才符合資格。已追蹤檔案已透過 git 存在，此步驟絕不會複製它們。OpenClaw 不會覆寫或變更已存在的目的地檔案、不會跟隨符號連結目錄，並會保留所複製檔案的模式。它只記錄實際建立的路徑，因此日後編輯資訊清單不會讓這些檔案失去清理保護。

## 執行儲存庫設定

如果原始碼儲存庫中存在 `.openclaw/worktree-setup.sh` 且可執行，OpenClaw 會以新 worktree 作為目前目錄來執行它。該指令碼會收到：

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_SOURCE_TREE_PATH=<source checkout>
OPENCLAW_WORKTREE_PATH=<managed worktree>
```

非零結束狀態會中止建立作業，並移除新的 worktree 與分支。這是儲存庫本機合約；沒有對應的 OpenClaw 設定鍵。

## 工作階段 worktree

若要從 git 支援的資料夾啟動隔離的聊天並使用 worktree 工作階段：請在 Control UI 的 New session 頁面中，使用 **Place** 選擇器選取閘道來源資料夾，然後選取 **Worktree**（可選擇性指定基準分支與 worktree 名稱）。只有在閘道確認所選資料夾是 Git 簽出後，此選項才會出現；一般資料夾會直接執行，且不顯示 Git 隔離控制項。當作用中的代理程式工作區由 Git 支援時，iOS 會從 Chat actions 提供相同選項，而 Android 則會在 New Chat 旁提供此選項。

程式設計代理程式在發現目前任務範圍外已確認的後續工作時，也可以呼叫 `spawn_task`。Control UI 會顯示建議籌碼，但不會啟動任何作業；由閘道支援的終端介面則會顯示具備相同動作的互動式提示。選取 **Start in worktree** 會從建議的專案建立新的工作階段專屬 worktree，並將完整且獨立的提示作為其第一輪訊息；關閉建議則不會變更儲存庫。建議及其 ID 為暫時性資料，閘道重新啟動後不會保留。

OpenClaw 只會向具備可操作閘道 UI 的操作員工作階段公開這些工具。在這些介面具備可攜式型別化任務動作合約之前，頻道工作階段及本機／內嵌終端介面工作階段不會取得這些工具。

產生的受管理 worktree 由工作階段擁有，該工作階段中的每次代理程式執行都會使用其簽出。當工作區是儲存庫子目錄時，worktree 會錨定於儲存庫根目錄，而工作階段則從其中對應的子目錄執行。工作階段 worktree 的建立會使用該方法的 `operator.write` 範圍，但儲存庫簽出掛鉤與 `.openclaw/worktree-setup.sh` 步驟只會為 `operator.admin` 呼叫者執行，因為它們會執行儲存庫程式碼；`.worktreeinclude` 佈建仍適用於每個呼叫者。只有在可以無損移除時，刪除工作階段才會移除 worktree。未清理的 worktree 或含有未推送提交的分支會保留；每小時清理會在工作階段 worktree 閒置 7 天後為其建立快照，並將近期工作階段活動視為 worktree 活動。已移除的 worktree 仍可依下述方式從快照還原。

`sessions.create` 可包含絕對 `cwd`，以便直接在另一個閘道資料夾中執行、搭配 `worktree: true` 選擇來源簽出，或設定配對節點的工作目錄。每個明確的主機路徑都需要 `operator.admin`；一般 worktree 聊天建立仍使用 `operator.write`，並保持錨定於已設定的工作區。

`sessions.create` 除了 `worktree: true` 外，也接受 `worktreeBaseRef` 與 `worktreeName`，以選取基準參照及 worktree 名稱（分支會成為 `openclaw/<name>`）；兩者都維持在 `operator.write`。建立的 worktree 會在建立結果中傳回，並以 `worktree: { id, branch, repoRoot }` 持久保存於工作階段資料列中，因此工作階段清單可以顯示簽出與分支。刪除工作階段時，若保留了未清理的簽出，會將其回報為 `worktreePreserved`，而不是默默將其留下。

## 快照、清理與還原

移除作業會先建立一個包含已追蹤檔案與未被忽略之未追蹤檔案的合成提交，然後將其固定於 `refs/openclaw/snapshots/<id>`。被忽略的檔案絕不會進入儲存庫物件資料庫。OpenClaw 只會將其實際佈建的已忽略檔案儲存在分塊的共用狀態資料庫資料列中；即使 `.worktreeinclude` 日後變更或消失，已記錄的路徑集合仍是權威依據。還原作業會從不可變的快照讀取這些位元組，並重新套用其完整模式。當已記錄的路徑無法再安全建立快照時，自動清理會保留現有 worktree。如果快照建立失敗，移除作業會停止。明確的強制刪除可以在沒有快照的情況下繼續。

OpenClaw 會套用下列清理規則：

* 執行結束時，只有當 `git status --porcelain` 為空，且 `git log HEAD --not --remotes --oneline` 未找到任何未推送提交時，才會移除 worktree。否則只會釋放活動鎖定。
* 每小時清理會為閒置超過 7 天且未鎖定、由 Workboard 或工作階段擁有的 worktree 建立快照並將其移除，即使它們尚未清理也一樣。手動 worktree 絕不會自動移除。
* 快照記錄會維持可還原狀態 30 天。之後清理作業會刪除快照參照與登錄資料列。
* 執行中的 OpenClaw 程序鎖定，以及任何外部或無法辨識的 git worktree 鎖定，都會保護 worktree 不被垃圾回收。

還原作業會在快照前的原始提交重新建立 `openclaw/<name>`，然後將快照差異重建為未暫存的修改與未追蹤檔案。如此可避免合成快照提交進入分支歷史。快照參照會保留記錄以作為來源證明。

## 命令列介面

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw worktrees list [--json]
openclaw worktrees create <repo-root> [--name <name>] [--base-ref <ref>] [--json]
openclaw worktrees remove <id> [--force] [--json]
openclaw worktrees restore <id> [--json]
openclaw worktrees gc [--json]
```

Settings 下的 Control UI **Worktrees** 頁面提供相同動作，另可透過基準分支選擇器建立 worktree；它會顯示每個 worktree 的擁有者（手動、Workboard，或擁有該 worktree 的工作階段，並提供前往其聊天的連結），且當移除作業回報快照失敗時，會提供強制重試選項。

## 閘道方法

| 方法                   | 用途                                        |
| -------------------- | ----------------------------------------- |
| `worktrees.list`     | 列出使用中及可還原的 worktree 記錄。                   |
| `worktrees.branches` | 列出儲存庫的本機與遠端分支，供基準參照選擇器使用。                 |
| `worktrees.create`   | 建立或重複使用具名的受管理 worktree。                   |
| `worktrees.remove`   | 建立快照並移除 worktree。強制移除會回報 `snapshotError`。 |
| `worktrees.restore`  | 從快照還原已移除的 worktree。                       |
| `worktrees.gc`       | 立即執行閒置、孤立項目及保留期限清理。                       |

`worktrees.list` 需要 `operator.read`，而會進行變更的方法需要 `operator.admin`。對於已設定的代理程式工作區，`worktrees.branches` 需要 `operator.write`；任何其他主機路徑則需要 `operator.admin`（符合 `sessions.create` 的目前工作目錄門檻）。它只讀取現有參照，絕不會擷取；僅存在於遠端的分支會以包含遠端限定詞的形式傳回（`origin/feature-a`），因此每個傳回的名稱都能解析為基準參照。New Session 也可以透過此方法要求型別化的儲存庫狀態；一般目錄或無法使用的簽出不會傳回任何分支，而不會迫使 UI 從錯誤字串推斷 Git 功能。

## Workboard 工作區

內建的 [Workboard 外掛](/zh-TW/plugins/workboard) 可以將卡片工作區具體化為受管理的 worktree：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "kind": "worktree",
  "path": "/absolute/path/to/source-checkout",
  "branch": "main"
}
```

`path` 用於識別來源 git 簽出。`branch` 為選填，並會成為基準參照。對於具有完整主機存取權的呼叫者，Workboard 會建立或重複使用 `wb-<card-id>`、以受管理的簽出作為工作目錄執行子代理程式，並將解析後的路徑與分支寫回卡片。閘道用戶端需要 `operator.admin` 才能進行完整主機具體化。執行結束時，Workboard 只有在可以證明移除無損時才會移除簽出；未清理的工作或未推送的提交會保留。

對於受工作區限制的呼叫者，`path` 與儲存庫根目錄必須和目標代理程式工作區完全相符。之後 Workboard 會直接在該目錄中執行，並記錄目錄工作區，而不會在主機上具體化受管理的 worktree。目標必須為相同工作區使用可寫入且非共用的 Docker 沙箱，其執行中容器的雜湊必須符合要求的掛載與政策，且不得公開提升權限的執行、主機控制、全主機工作階段、持久化的主機／節點執行，或未分類的外掛與 MCP 工具。如果目標政策或執行中容器的範圍更廣，分派作業會讓卡片維持未認領狀態，並回報不相容狀態。