Sandbox CLI

エージェントの隔離実行のためのDockerベースサンドボックスコンテナを管理します。

概要

OpenClawはセキュリティのためにエージェントを隔離されたDockerコンテナで実行できます。sandbox コマンドはこれらのコンテナの管理を支援し、特にアップデートや設定変更後に有用です。

コマンド

`openclaw sandbox explain`

有効なサンドボックスモード/スコープ/ワークスペースアクセス、サンドボックスツールポリシー、昇格ゲート（修正用の設定キーパス付き）を確認します。

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

`openclaw sandbox list`

すべてのサンドボックスコンテナのステータスと設定を一覧表示します。

openclaw sandbox list
openclaw sandbox list --browser  # ブラウザコンテナのみ表示
openclaw sandbox list --json     # JSON出力

出力内容:

コンテナ名とステータス（running/stopped）
Dockerイメージと設定との一致状況
経過時間（作成からの時間）
アイドル時間（最後に使用されてからの時間）
関連付けられたセッション/エージェント

`openclaw sandbox recreate`

更新されたイメージ/設定で再作成するためにサンドボックスコンテナを削除します。

openclaw sandbox recreate --all                # すべてのコンテナを再作成
openclaw sandbox recreate --session main       # 特定のセッション
openclaw sandbox recreate --agent mybot        # 特定のエージェント
openclaw sandbox recreate --browser            # ブラウザコンテナのみ
openclaw sandbox recreate --all --force        # 確認をスキップ

オプション:

--all: すべてのサンドボックスコンテナを再作成
--session <key>: 特定セッションのコンテナを再作成
--agent <id>: 特定エージェントのコンテナを再作成
--browser: ブラウザコンテナのみ再作成
--force: 確認プロンプトをスキップ

重要: コンテナはエージェントの次回使用時に自動的に再作成されます。

ユースケース

Dockerイメージの更新後

# 新しいイメージをプル
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim

# 設定を更新して新しいイメージを使用
# 設定を編集: agents.defaults.sandbox.docker.image（または agents.list[].sandbox.docker.image）

# コンテナを再作成
openclaw sandbox recreate --all

サンドボックス設定の変更後

# 設定を編集: agents.defaults.sandbox.*（または agents.list[].sandbox.*）

# 再作成して新しい設定を適用
openclaw sandbox recreate --all

setupCommandの変更後

openclaw sandbox recreate --all
# または特定のエージェントのみ:
openclaw sandbox recreate --agent family

特定のエージェントのみ

# 1つのエージェントのコンテナのみ更新
openclaw sandbox recreate --agent alfred

なぜこれが必要なのか

問題: サンドボックスのDockerイメージや設定を更新した場合:

既存のコンテナは古い設定のまま実行され続けます
コンテナは24時間の非アクティブ後にのみプルーニングされます
定期的に使用されるエージェントは古いコンテナを無期限に維持します

解決策: openclaw sandbox recreate で古いコンテナの強制削除を行います。次に必要になった時に現在の設定で自動的に再作成されます。

ヒント: 手動の docker rm よりも openclaw sandbox recreate を優先してください。Gatewayのコンテナ命名規則を使用し、スコープ/セッションキーの変更時の不整合を回避します。

設定

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

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "containerPrefix": "openclaw-sbx-",
          // ... その他のDockerオプション
        },
        "prune": {
          "idleHours": 24, // 24時間アイドル後に自動プルーニング
          "maxAgeDays": 7, // 7日後に自動プルーニング
        },
      },
    },
  },
}