管理対象のワークツリー

管理対象の worktree は、一時ディレクトリをソースリポジトリ内に配置することなく、エージェントタスクごとに専用の git ブランチとチェックアウトを提供します。OpenClaw はそれらを状態ディレクトリ配下に作成し、共有状態データベースに記録し、削除前に追跡対象の内容と、無視されていない未追跡の内容をスナップショットとして保存します。

レイアウトと名前

各 worktree は次の場所に配置されます。

<openclaw-state-dir>/worktrees/<repo-fingerprint>/<name>

リポジトリフィンガープリントは、正規化された git 共通ディレクトリと origin URL を基に計算した SHA-256 ハッシュの先頭 16 桁の 16 進文字です。指定する名前は [a-z0-9][a-z0-9-]{0,63} に一致する必要があります。名前を指定しない場合、OpenClaw は wt- の後にランダムな 8 桁の 16 進文字を付けて生成します。

OpenClaw は、要求されたベース ref にブランチ openclaw/<name> を作成します。ベース ref を指定しない場合は origin をフェッチし、利用可能であればリモートのデフォルトブランチを使用します。リポジトリがオフラインであるか、使用可能なリモートがない場合は、ローカルの HEAD にフォールバックします。

無視対象ファイルのプロビジョニング

選択した無視対象の未追跡ファイルを新しい worktree にコピーするには、ソースリポジトリのルートに .worktreeinclude を追加します。このファイルでは gitignore パターン構文を使用し、1 行に 1 パターンを記述します。コメントには # を使用します。

.env.localfixtures/generated/**

対象になるのは、git によって無視対象かつ未追跡として報告されたファイルのみです。追跡対象ファイルは git を通じてすでに存在するため、この手順ではコピーされません。OpenClaw はコピー先のファイルを上書きせず、シンボリックリンクされたディレクトリをたどりません。また、コピーしたファイルのモードを保持します。

リポジトリセットアップの実行

ソースリポジトリに .openclaw/worktree-setup.sh が存在し、実行可能である場合、OpenClaw は新しい worktree をカレントディレクトリとしてそれを実行します。スクリプトには次の値が渡されます。

OPENCLAW_SOURCE_TREE_PATH=<source checkout>OPENCLAW_WORKTREE_PATH=<managed worktree>

0 以外の終了コードが返されると作成は中止され、新しい worktree とブランチが削除されます。これはリポジトリローカルの契約であり、対応する OpenClaw 設定キーはありません。

セッション worktree

アクティブなエージェントの git ワークスペースから、worktree を使用するセッションとして分離されたチャットを開始できます。Control UI の「新規セッション」ページで Worktree を有効にするか（ベースブランチの選択と任意の worktree 名も指定できます）、iOS ではチャットアクションメニュー、Android では「新規チャット」の横にあるオーバーフローアクションを使用します。このオプションは、クライアントがその機能を備えた git ベースのエージェントでのみ利用できます。事前検証できないクライアントでは、代わりに Gateway エラーが表示されます。

コーディングエージェントは、現在のタスク外で対応が必要なフォローアップ作業を確認した場合、spawn_task を呼び出すこともできます。Control UI は何も開始せずに提案チップを表示し、Gateway ベースの TUI は同じアクションを備えた対話型プロンプトを表示します。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 に worktree: true とともに絶対 cwd を含めることができます。この明示的なホストパスには operator.admin が必要です。通常の worktree チャット作成は引き続き operator.write であり、設定済みのワークスペースを基準にします。

sessions.create は、ベース ref と worktree 名を選択するために、worktree: true とともに worktreeBaseRef および worktreeName も受け付けます（ブランチは openclaw/<name> になります）。どちらも operator.write のままです。作成された worktree は作成結果で返され、セッション行に worktree: { id, branch, repoRoot } として永続化されるため、セッション一覧にチェックアウトとブランチを表示できます。セッションを削除する際、変更のあるチェックアウトを保持した場合は、暗黙に残すのではなく worktreePreserved として報告されます。

スナップショット、クリーンアップ、復元

削除時にはまず、追跡対象ファイルと無視されていない未追跡ファイルを含む合成コミットを作成し、refs/openclaw/snapshots/<id> に固定します。gitignore の対象ファイルはリポジトリのオブジェクトデータベースから除外されます。.worktreeinclude で選択されたファイルは、復元時に再度コピーされます。スナップショットの作成に失敗すると、削除は停止します。明示的な強制削除では、スナップショットなしで続行できます。

OpenClaw は次のクリーンアップルールを適用します。

• 実行終了時、git status --porcelain が空であり、かつ git log HEAD --not --remotes --oneline で未プッシュコミットが検出されない場合に限り、worktree を削除します。それ以外の場合は、アクティビティロックのみを解放します。
• 1 時間ごとのクリーンアップでは、ロックされておらず、7 日を超えてアイドル状態の Workboard 所有およびセッション所有の worktree を、変更の有無にかかわらずスナップショットとして保存して削除します。手動 worktree は自動的に削除されません。
• worktrees.cleanup.maxCount または worktrees.cleanup.maxTotalSizeGb が設定されている場合、worktree の合計数とディスクサイズが上限内に収まるまで、最近のアクティビティが最も古い Workboard 所有およびセッション所有の worktree もスナップショットとして保存して削除します。すべての管理対象 worktree が合計に含まれますが、手動 worktree およびその他の保護対象 worktree は上限超過によって削除されません。そのため、削除可能な worktree が存在するまで上限超過が続く場合があります。0 または未設定の場合、その上限は無効になります。
• スナップショットレコードは 30 日間復元できます。その後、クリーンアップによってスナップショット ref とレジストリ行が削除されます。
• 実行中の OpenClaw プロセスによるロック、および外部または認識されていない git worktree ロックは、worktree をガベージコレクションから保護します。

復元では、元のスナップショット作成前のコミットに openclaw/<name> を再作成し、スナップショットの差分をステージされていない変更と未追跡ファイルとして再構築します。これにより、合成スナップショットコミットはブランチ履歴に含まれません。スナップショット ref は来歴情報として引き続き記録されます。

CLI

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]

Control UI の「設定」にある Worktree ページでは、同じアクションに加えてベースブランチを選択して作成できます。また、各 worktree の所有者（手動、Workboard、またはそのチャットへのリンク付きの所有セッション）を表示し、削除時にスナップショット失敗が報告された場合は強制再試行を実行できます。その クリーンアップ セクションでは、設定リファレンスで説明されている worktrees.cleanup 保持上限を編集できます。

Gateway メソッド

worktrees.list には operator.read が必要であり、変更を行うメソッドには operator.admin が必要です。設定済みのエージェントワークスペースに対する worktrees.branches には operator.write が必要ですが、それ以外のホストパスには operator.admin が必要です（sessions.create の cwd 要件と同じです）。既存の ref のみを読み取り、フェッチは行いません。リモートにしか存在しないブランチはリモート修飾形式（origin/feature-a）で返されるため、返されたすべての名前をベース ref として解決できます。

Workboard ワークスペース

同梱の Workboard Pluginでは、カードのワークスペースを管理対象 worktree として実体化できます。

{  "kind": "worktree",  "path": "/absolute/path/to/source-checkout",  "branch": "main"}

path はソース git チェックアウトを識別します。branch は任意であり、ベース ref になります。フルホスト呼び出し元では、Workboard は wb-<card-id> を作成または再利用し、管理対象チェックアウトを作業ディレクトリとしてサブエージェントを実行し、解決済みのパスとブランチをカードに書き戻します。Gateway クライアントでフルホスト実体化を行うには operator.admin が必要です。実行終了時、Workboard は損失なく削除できることが証明できる場合に限りチェックアウトを削除します。変更のある作業や未プッシュコミットは引き続き利用できます。

ワークスペースに制約された呼び出し元では、path とリポジトリルートが対象エージェントワークスペースに完全に一致する必要があります。その場合、Workboard はそのディレクトリで直接実行し、管理対象 worktree をホスト上に実体化する代わりに、ディレクトリワークスペースを記録します。対象では、同じワークスペースに対して書き込み可能かつ非共有の Docker サンドボックスを使用する必要があり、実行中コンテナのハッシュが要求されたマウントおよびポリシーと一致していなければなりません。また、権限昇格された実行、ホスト制御、ホスト全体のセッション、永続化されたホストまたは Node 実行、分類されていない Plugin および MCP ツールを公開してはなりません。対象ポリシーまたは実行中コンテナの権限範囲がそれより広い場合、ディスパッチはカードを未割り当てのままにし、互換性のない状態を報告します。