レイアウトと名前
各 worktree は次の場所に配置されます。[a-z0-9][a-z0-9-]{0,63} と一致する必要があります。名前を指定しない場合、OpenClaw は wt- にランダムな 16 進文字 8 桁を続けた名前を生成します。
OpenClaw は、要求されたベース ref にブランチ openclaw/<name> を作成します。ベース ref を指定しない場合、origin を fetch し、利用可能であればリモートのデフォルトブランチを使用します。リポジトリがオフラインであるか、使用可能なリモートがない場合は、ローカルの HEAD にフォールバックします。
無視対象ファイルの用意
選択した無視対象の未追跡ファイルを新しい worktree にコピーするには、ソースリポジトリのルートに.worktreeinclude を追加します。このファイルでは gitignore パターン構文を使用し、1 行に 1 パターンを記述します。# はコメントです。
リポジトリセットアップの実行
ソースリポジトリに.openclaw/worktree-setup.sh が存在し、実行可能である場合、OpenClaw は新しい worktree をカレントディレクトリとしてそれを実行します。スクリプトには次の値が渡されます。
セッション 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/<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 を削除します。それ以外の場合は、アクティビティロックのみを解放します。 - 1 時間ごとのクリーンアップでは、ロックされておらず、7 日を超えてアイドル状態にある Workboard 所有およびセッション所有の worktree を、変更の有無にかかわらずスナップショット化して削除します。手動の worktree は自動的に削除されません。
- スナップショットレコードは 30 日間復元可能です。その後、クリーンアップによってスナップショット ref とレジストリ行が削除されます。
- 稼働中の OpenClaw プロセスロック、および外部または認識されていない Git worktree ロックがある場合、その worktree はガベージコレクションの対象になりません。
openclaw/<name> を再作成し、スナップショットとの差分をステージされていない変更と未追跡ファイルとして再構築します。これにより、合成スナップショットコミットがブランチ履歴に入ることを防ぎます。スナップショット ref は来歴情報として記録されたままになります。
CLI
Gateway メソッド
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 は、カードのワークスペースを管理対象 worktree として実体化できます。path はソース Git チェックアウトを識別します。branch は任意で、ベース ref になります。フルホスト呼び出し元の場合、Workboard は wb-<card-id> を作成または再利用し、管理対象チェックアウトを作業ディレクトリとしてサブエージェントを実行し、解決されたパスとブランチをカードに書き戻します。Gateway クライアントがフルホストで実体化するには operator.admin が必要です。実行終了時、Workboard は損失がないことを確実に証明できる場合にのみチェックアウトを削除します。変更がある作業内容や未プッシュのコミットは利用可能な状態で保持されます。
ワークスペースに制約された呼び出し元の場合、path とリポジトリルートは、対象エージェントワークスペースと完全に一致する必要があります。その場合、Workboard はそのディレクトリで直接実行し、管理対象 worktree をホスト上に実体化する代わりに、ディレクトリワークスペースを記録します。対象では、同じワークスペースに対して書き込み可能かつ非共有の Docker サンドボックスを使用する必要があります。また、稼働中コンテナのハッシュが要求されたマウントおよびポリシーと一致し、昇格実行、ホスト制御、ホスト全体のセッション、永続化されたホスト／Node 実行、または分類されていない Plugin および MCP ツールを公開してはなりません。対象のポリシーまたは稼働中コンテナの権限範囲がこれより広い場合、ディスパッチはカードを未取得のままにし、非互換状態を報告します。