--- read_when: - エージェントタスク用に分離されたブランチとチェックアウトが必要な場合 - worktree ワークスペースで Workboard カードを設定しています - OpenClaw が管理するワークツリーを復元またはクリーンアップする必要があります summary: 自動スナップショットとクリーンアップを使用して、分離された git チェックアウトでエージェントタスクを実行する title: 管理対象のワークツリー x-i18n: generated_at: "2026-07-26T09:38:02Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 98ed2579b7243544dbdb550c4b8a292ccd4ab494fd4a45b2404256691c831401 source_path: concepts/managed-worktrees.md workflow: 16 --- 管理対象の worktree を使用すると、ソースリポジトリ内に一時ディレクトリを作成せず、エージェントタスク専用の git ブランチとチェックアウトを用意できます。OpenClaw はそれらを状態ディレクトリ配下に作成し、共有状態データベースに記録したうえで、削除前に追跡対象の内容と、無視対象ではない未追跡の内容のスナップショットを作成します。 ## レイアウトと名前 各 worktree は次の場所に配置されます。 ```text /worktrees// ``` リポジトリフィンガープリントは、正規化された git 共通ディレクトリと origin URL を対象とする SHA-256 ハッシュの先頭 16 桁の 16 進文字です。指定する名前は `[a-z0-9][a-z0-9-]{0,63}` と一致する必要があります。名前を指定しない場合、OpenClaw は `wt-` にランダムな 16 進文字 8 桁を続けた名前を生成します。 OpenClaw は、要求されたベース ref にブランチ `openclaw/` を作成します。ベース ref を指定しない場合、`origin` を fetch し、利用可能であればリモートのデフォルトブランチを使用します。リポジトリがオフラインであるか、使用可能なリモートがない場合は、ローカルの `HEAD` にフォールバックします。 ## 無視対象ファイルの用意 選択した無視対象の未追跡ファイルを新しい worktree にコピーするには、ソースリポジトリのルートに `.worktreeinclude` を追加します。このファイルでは gitignore パターン構文を使用し、1 行に 1 パターンを記述します。`#` はコメントです。 ```gitignore .env.local fixtures/generated/** ``` git によって無視対象かつ未追跡と報告されたファイルのみが対象になります。追跡対象ファイルは git によってすでに存在するため、この手順では決してコピーされません。OpenClaw は、すでに存在するコピー先ファイルを上書きまたは変更せず、シンボリックリンクされたディレクトリをたどらず、コピーしたファイルのモードを保持します。実際に作成したパスのみを記録するため、後からマニフェストを編集しても、それらのファイルがクリーンアップ保護の対象から外れることはありません。 ## リポジトリセットアップの実行 ソースリポジトリに `.openclaw/worktree-setup.sh` が存在し、実行可能である場合、OpenClaw は新しい worktree をカレントディレクトリとしてそれを実行します。スクリプトには次の値が渡されます。 ```text OPENCLAW_SOURCE_TREE_PATH= OPENCLAW_WORKTREE_PATH= ``` 0 以外の終了コードが返されると作成は中止され、新しい worktree とブランチが削除されます。これはリポジトリローカルの契約であり、対応する OpenClaw 設定キーはありません。 ## セッション worktree Git で管理されたフォルダーから分離されたチャットを開始するには、worktree セッションを使用します。Control UI の New session ページで、**Place** ピッカーを使用して Gateway のソースフォルダーを選択し、次に **Worktree** を選択します（ベースブランチと worktree 名は任意です）。この選択肢は、選択したフォルダーが Git チェックアウトであることを Gateway が確認した後にのみ表示されます。通常のフォルダーは直接実行され、Git 分離コントロールは表示されません。アクティブなエージェントワークスペースが Git で管理されている場合、iOS では Chat actions から、Android では New Chat の横から同じ選択肢を利用できます。 コーディングエージェントは、現在のタスクの範囲外にある、確認済みの後続作業を発見した場合に `spawn_task` を呼び出すこともできます。Control UI には何も開始せずに提案チップが表示され、Gateway を利用する TUI には同じアクションを含む対話型プロンプトが表示されます。**Start in worktree** を選択すると、提案されたプロジェクトからセッション所有の新しい worktree が作成され、自己完結したプロンプトが最初のターンとして送信されます。提案を閉じた場合、リポジトリには何も変更されません。提案とその ID は一時的なものであり、Gateway の再起動後には保持されません。 OpenClaw は、操作可能な Gateway UI を備えたオペレーターセッションにのみ、これらのツールを公開します。チャンネルセッションおよびローカル／組み込み TUI セッションには、それらのサーフェスに移植可能な型付きタスクアクション契約が導入されるまで、これらのツールは提供されません。 生成される管理対象 worktree はセッションによって所有され、そのセッション内のすべてのエージェント実行でそのチェックアウトが使用されます。ワークスペースがリポジトリのサブディレクトリである場合、worktree はリポジトリルートを基準に作成され、セッションはその内部の対応するサブディレクトリから実行されます。セッション worktree の作成では、メソッドの `operator.write` スコープが使用されますが、リポジトリのチェックアウトフックと `.openclaw/worktree-setup.sh` ステップはリポジトリコードを実行するため、`operator.admin` 呼び出し元に対してのみ実行されます。`.worktreeinclude` のプロビジョニングは、引き続きすべての呼び出し元に適用されます。セッションを削除すると、損失なく削除できる場合にのみ worktree も削除されます。変更がある worktree や、未プッシュのコミットがあるブランチは利用可能な状態で保持されます。1 時間ごとのクリーンアップでは、最近のセッションアクティビティを worktree のアクティビティとして扱い、7 日間アイドル状態だったセッション worktree のスナップショットを作成します。削除された worktree は、以下の説明に従ってスナップショットから復元できます。 `sessions.create` には、別の Gateway フォルダーで直接実行するため、`worktree: true` と組み合わせてソースチェックアウトを選択するため、またはペアリングされた Node の作業ディレクトリを設定するための絶対 `cwd` を含めることができます。明示的なホストパスにはすべて `operator.admin` が必要です。通常の worktree チャット作成は引き続き `operator.write` であり、設定されたワークスペースを基準とします。 `sessions.create` では、`worktree: true` に加えて `worktreeBaseRef` と `worktreeName` も指定でき、ベース ref と worktree 名を選択できます（ブランチは `openclaw/` になります）。どちらも `operator.write` のままです。作成された worktree は作成結果として返され、セッション行に `worktree: { id, branch, repoRoot }` として永続化されるため、セッション一覧にチェックアウトとブランチを表示できます。セッションを削除する際、変更があるチェックアウトを保持した場合は、暗黙的に残すのではなく `worktreePreserved` として報告されます。 ## スナップショット、クリーンアップ、復元 削除時には、まず追跡対象ファイルと無視されていない未追跡ファイルを含む合成コミットが作成され、`refs/openclaw/snapshots/` に固定されます。無視対象ファイルがリポジトリのオブジェクトデータベースに入ることはありません。OpenClaw は、実際にプロビジョニングした無視対象ファイルのみを、チャンク化された共有状態データベース行に保存します。後から `.worktreeinclude` が変更または消失しても、記録されたパスセットが引き続き正式な基準となります。復元では、不変のスナップショットからそれらのバイトを読み取り、完全なモードを再適用します。記録されたパスを安全にスナップショット化できなくなった場合、自動クリーンアップは稼働中の worktree を保持します。スナップショットの作成に失敗すると、削除は停止します。明示的な強制削除では、スナップショットなしで続行できます。 OpenClaw は次のクリーンアップルールを適用します。 - 実行終了時、`git status --porcelain` が空で、かつ `git log HEAD --not --remotes --oneline` で未プッシュのコミットが見つからない場合にのみ、worktree を削除します。それ以外の場合は、アクティビティロックのみを解放します。 - 1 時間ごとのクリーンアップでは、ロックされておらず、7 日を超えてアイドル状態にある Workboard 所有およびセッション所有の worktree を、変更の有無にかかわらずスナップショット化して削除します。手動の worktree は自動的に削除されません。 - スナップショットレコードは 30 日間復元可能です。その後、クリーンアップによってスナップショット ref とレジストリ行が削除されます。 - 稼働中の OpenClaw プロセスロック、および外部または認識されていない Git worktree ロックがある場合、その worktree はガベージコレクションの対象になりません。 復元では、元のスナップショット前コミットに `openclaw/` を再作成し、スナップショットとの差分をステージされていない変更と未追跡ファイルとして再構築します。これにより、合成スナップショットコミットがブランチ履歴に入ることを防ぎます。スナップショット ref は来歴情報として記録されたままになります。 ## CLI ```bash openclaw worktrees list [--json] openclaw worktrees create [--name ] [--base-ref ] [--json] openclaw worktrees remove [--force] [--json] openclaw worktrees restore [--json] openclaw worktrees gc [--json] ``` Settings 配下の Control UI **Worktrees** ページでは、同じ操作に加えてベースブランチ選択による作成が可能です。また、各 worktree の所有者（手動、Workboard、またはチャットへのリンク付きの所有セッション）を表示し、削除でスナップショット失敗が報告された場合には強制再試行を提供します。 ## Gateway メソッド | メソッド | 目的 | | -------------------- | ----------------------------------------------------------------------- | | `worktrees.list` | アクティブおよび復元可能な worktree レコードを一覧表示します。 | | `worktrees.branches` | ベース ref 選択用に、リポジトリのローカルブランチとリモートブランチを一覧表示します。 | | `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` の cwd 基準と一致します）。既存の ref のみを読み取り、fetch は一切行いません。また、リモートにのみ存在するブランチはリモート修飾された形式（`origin/feature-a`）で返されるため、返されるすべての名前をベース ref として解決できます。New Session は、このメソッドから型付きのリポジトリステータスを要求することもできます。通常のディレクトリまたは利用できないチェックアウトの場合、UI にエラー文字列から Git 機能を推測させるのではなく、ブランチなしとして返します。 ## Workboard ワークスペース バンドルされている [Workboard Plugin](/ja-JP/plugins/workboard) は、カードのワークスペースを管理対象 worktree として実体化できます。 ```json { "kind": "worktree", "path": "/absolute/path/to/source-checkout", "branch": "main" } ``` `path` はソース Git チェックアウトを識別します。`branch` は任意で、ベース ref になります。フルホスト呼び出し元の場合、Workboard は `wb-` を作成または再利用し、管理対象チェックアウトを作業ディレクトリとしてサブエージェントを実行し、解決されたパスとブランチをカードに書き戻します。Gateway クライアントがフルホストで実体化するには `operator.admin` が必要です。実行終了時、Workboard は損失がないことを確実に証明できる場合にのみチェックアウトを削除します。変更がある作業内容や未プッシュのコミットは利用可能な状態で保持されます。 ワークスペースに制約された呼び出し元の場合、`path` とリポジトリルートは、対象エージェントワークスペースと完全に一致する必要があります。その場合、Workboard はそのディレクトリで直接実行し、管理対象 worktree をホスト上に実体化する代わりに、ディレクトリワークスペースを記録します。対象では、同じワークスペースに対して書き込み可能かつ非共有の Docker サンドボックスを使用する必要があります。また、稼働中コンテナのハッシュが要求されたマウントおよびポリシーと一致し、昇格実行、ホスト制御、ホスト全体のセッション、永続化されたホスト／Node 実行、または分類されていない Plugin および MCP ツールを公開してはなりません。対象のポリシーまたは稼働中コンテナの権限範囲がこれより広い場合、ディスパッチはカードを未取得のままにし、非互換状態を報告します。