サンドボックス 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（デフォルトは 24h）後にのみ削除されます。定期的に使用されるエージェントでは、古いランタイムが無期限に存続する可能性があります。openclaw sandbox recreate は古いランタイムを削除し、次回使用時に現在の設定から再構築されるようにします。

一般的な契機

レジストリの移行

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

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

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

設定

サンドボックス設定は、~/.openclaw/openclaw.json 内の agents.defaults.sandbox にあります（エージェントごとの上書きは agents.entries.*.sandbox に配置します）。

{  "agents": {    "defaults": {      "sandbox": {        "mode": "all", // off、non-main、all        "backend": "docker", // docker、ssh、openshell（Plugin によって提供）        "scope": "agent", // session、agent、shared        "docker": {          "image": "openclaw-sandbox:bookworm-slim",          "containerPrefix": "openclaw-sbx-",          // ... その他の Docker オプション        },        "prune": {          "idleHours": 24, // 24h のアイドル後に自動削除          "maxAgeDays": 7, // 7 日後に自動削除        },      },    },  },}

関連項目

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