サンドボックス CLI

分離されたエージェント実行用のサンドボックスランタイム（Docker コンテナ、SSH ターゲット、OpenShell バックエンド）を管理します。

コマンド

openclaw sandbox list

サンドボックスランタイムを、ステータス、バックエンド、設定の一致状況、経過時間、アイドル時間、関連付けられたセッション／エージェントとともに一覧表示します。

openclaw sandbox listopenclaw sandbox list --browser  # ブラウザーコンテナのみopenclaw sandbox list --json

openclaw sandbox recreate

サンドボックスランタイムを削除し、現在の設定で強制的に再作成します。ランタイムは、次にエージェントが使用されたときに自動的に再作成されます。

openclaw sandbox recreate --allopenclaw sandbox recreate --agent mybot        # agent:mybot:* サブセッションを含むopenclaw sandbox recreate --session "agent:main:main"openclaw sandbox recreate --browser --all      # ブラウザーコンテナのみopenclaw sandbox recreate --all --force        # 確認を省略

オプション：

• --all：すべてのサンドボックスコンテナを再作成
• --session <key>：この完全一致のスコープキー（sandbox list に表示されるもの）を持つランタイムを再作成。短縮名の展開は行わない
• --agent <id>：1 つのエージェントのランタイムを再作成（agent:<id> および agent:<id>:* に一致）
• --browser：ブラウザーコンテナのみに適用
• --force：確認プロンプトを省略

--all、--session、--agent のいずれか 1 つだけを指定してください。

ssh および OpenShell の remote では、再作成は Docker の場合よりも重要です。初回シード後はリモートワークスペースが正規のワークスペースとなり、recreate は選択したスコープの正規リモートワークスペースを削除します。次回の実行時に、現在のローカルワークスペースから再シードされます。

openclaw sandbox explain

有効なサンドボックスのモード／スコープ／ワークスペースアクセス、サンドボックスのツールポリシー、および昇格ツールのゲートを調査します（修正用の設定キーパスを含む）。

レポートでは、workspaceRoot を設定済みのサンドボックスルートとして維持し、有効なホストワークスペース、バックエンドランタイムの作業ディレクトリ、Docker マウントテーブルを個別に表示します。workspaceAccess: "rw" の場合、有効なホストワークスペースは workspaceRoot 配下のディレクトリではなく、エージェントワークスペースです。

openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

recreate --session とは異なり、これは短いセッション名（例：main）を受け入れ、解決されたエージェントに対して展開します。

再作成が必要な理由

サンドボックス設定を更新しても、実行中のコンテナには反映されません。既存のランタイムは古い設定を保持し、アイドル状態のランタイムは prune.idleHours（デフォルトは 24 時間）を経過した後にのみ削除されます。定期的に使用されるエージェントでは、古いランタイムが無期限に維持される可能性があります。openclaw sandbox recreate は古いランタイムを削除し、次回の使用時に現在の設定から再構築されるようにします。

一般的な実行契機

レジストリの移行

サンドボックスランタイムのメタデータは、共有 SQLite 状態データベースに保存されます。古いインストールには、通常の読み取りでは書き換えられなくなった従来のレジストリファイルが存在する場合があります。

• ~/.openclaw/sandbox/containers.json
• ~/.openclaw/sandbox/browsers.json
• ~/.openclaw/sandbox/containers/ または ~/.openclaw/sandbox/browsers/ 配下にある、コンテナ／ブラウザーごとの JSON シャード

openclaw doctor --fix を実行して、有効な従来のエントリを SQLite に移行してください。無効な従来のファイルは隔離されるため、破損した古いレジストリによって現在のランタイムエントリが隠されることはありません。

設定

サンドボックス設定は、~/.openclaw/openclaw.json の agents.defaults.sandbox 配下にあります（エージェントごとのオーバーライドは agents.list[].sandbox に設定します）。

{  "agents": {    "defaults": {      "sandbox": {        "mode": "all", // オフ、メイン以外、すべて        "backend": "docker", // docker、ssh、openshell（Plugin が提供）        "scope": "agent", // セッション、エージェント、共有        "docker": {          "image": "openclaw-sandbox:bookworm-slim",          "containerPrefix": "openclaw-sbx-",          // ... その他の Docker オプション        },        "prune": {          "idleHours": 24, // 24 時間アイドル状態が続いた後に自動削除          "maxAgeDays": 7, // 7 日後に自動削除        },      },    },  },}

関連項目

• CLI リファレンス
• サンドボックス化
• エージェントワークスペース
• Doctor：サンドボックスのセットアップを確認します。