サンドボックス化

OpenClaw は、影響範囲を減らすために サンドボックスバックエンド内でツールを実行できます。これは任意であり、設定（agents.defaults.sandbox または agents.list[].sandbox）によって制御されます。サンドボックス化がオフの場合、ツールはホスト上で実行されます。Gateway はホスト上に残り、有効化されている場合はツール実行が分離されたサンドボックス内で実行されます。

サンドボックス化されるもの

• ツール実行（exec、read、write、edit、apply_patch、process など）。
• 任意のサンドボックス化ブラウザー（agents.defaults.sandbox.browser）。

サンドボックス化されないもの:

• Gateway プロセス自体。
• サンドボックス外で実行することを明示的に許可されたツール（例: tools.elevated）。
  • 昇格された exec はサンドボックス化を迂回し、設定済みのエスケープパス（デフォルトは gateway、exec 対象が node の場合は node）を使用します。
  • サンドボックス化がオフの場合、tools.elevated は実行を変更しません（すでにホスト上です）。昇格モードを参照してください。

モード

agents.defaults.sandbox.mode は、サンドボックス化をいつ使用するかを制御します:

スコープ

agents.defaults.sandbox.scope は、作成されるコンテナー数を制御します:

• "agent"（デフォルト）: agent ごとに 1 つのコンテナー。
• "session": セッションごとに 1 つのコンテナー。
• "shared": すべてのサンドボックス化セッションで共有される 1 つのコンテナー。

バックエンド

agents.defaults.sandbox.backend は、どのランタイムがサンドボックスを提供するかを制御します:

• "docker"（サンドボックス化が有効な場合のデフォルト）: ローカルの Docker ベースのサンドボックスランタイム。
• "ssh": 汎用 SSH ベースのリモートサンドボックスランタイム。
• "openshell": OpenShell ベースのサンドボックスランタイム。

SSH 固有の設定は agents.defaults.sandbox.ssh 配下にあります。OpenShell 固有の設定は plugins.entries.openshell.config 配下にあります。

バックエンドの選択

Docker バックエンド

サンドボックス化はデフォルトでオフです。サンドボックス化を有効にしてバックエンドを選択しない場合、OpenClaw は Docker バックエンドを使用します。Docker デーモンソケット（/var/run/docker.sock）経由で、ツールとサンドボックスブラウザーをローカルに実行します。サンドボックスコンテナーの分離は Docker 名前空間によって決まります。

ホスト GPU を Docker サンドボックスに公開するには、agents.defaults.sandbox.docker.gpus または agent ごとの agents.list[].sandbox.docker.gpus オーバーライドを設定します。この値は Docker の --gpus フラグに別個の引数として渡されます。例として "all" または "device=GPU-uuid" があり、NVIDIA Container Toolkit などの互換性のあるホストランタイムが必要です。

SSH バックエンド

任意の SSH アクセス可能マシン上で OpenClaw に exec、ファイルツール、メディア読み取りをサンドボックス化させたい場合は、backend: "ssh" を使用します。

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        scope: "session",        workspaceAccess: "rw",        ssh: {          target: "user@gateway-host:22",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // Or use SecretRefs / inline contents instead of local files:          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

OpenShell バックエンド

OpenShell 管理のリモート環境で OpenClaw にツールをサンドボックス化させたい場合は、backend: "openshell" を使用します。完全なセットアップガイド、設定リファレンス、ワークスペースモードの比較については、専用の OpenShell ページを参照してください。

OpenShell は、汎用 SSH バックエンドと同じコア SSH トランスポートおよびリモートファイルシステムブリッジを再利用し、OpenShell 固有のライフサイクル（sandbox create/get/delete、sandbox ssh-config）と任意の mirror ワークスペースモードを追加します。

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote", // mirror | remote          remoteWorkspaceDir: "/sandbox",          remoteAgentWorkspaceDir: "/agent",        },      },    },  },}

OpenShell モード:

• mirror（デフォルト）: ローカルワークスペースが正準のままです。OpenClaw は exec の前にローカルファイルを OpenShell に同期し、exec の後にリモートワークスペースを同期して戻します。
• remote: サンドボックス作成後は OpenShell ワークスペースが正準です。OpenClaw はローカルワークスペースからリモートワークスペースを一度シードし、その後ファイルツールと exec は変更を同期して戻さずにリモートサンドボックスに対して直接実行されます。

ワークスペースモード

OpenShell には 2 つのワークスペースモデルがあります。実際にはここが最も重要な部分です。

サンドボックスを一時的な実行環境と考える場合は mirror を選択します。サンドボックスを実際のワークスペースと考える場合は remote を選択します。

OpenShell ライフサイクル

OpenShell サンドボックスは、通常のサンドボックスライフサイクルを通じて引き続き管理されます。

• openclaw sandbox list は Docker ランタイムだけでなく OpenShell ランタイムも表示します
• openclaw sandbox recreate は現在のランタイムを削除し、次回使用時に OpenClaw が再作成できるようにします
• prune ロジックもバックエンドを認識します

remote モードでは、再作成が特に重要です。

• 再作成により、そのスコープの正規リモートワークスペースが削除されます
• 次回使用時に、ローカルワークスペースから新しいリモートワークスペースがシードされます

mirror モードでは、ローカルワークスペースがいずれにせよ正規のままなので、再作成は主にリモート実行環境をリセットします。

ワークスペースアクセス

agents.defaults.sandbox.workspaceAccess は、サンドボックスが何を参照できるかを制御します。

OpenShell バックエンドでは次のようになります。

• mirror モードでは、exec ターン間の正規ソースとして引き続きローカルワークスペースを使用します
• remote モードでは、初回シード後の正規ソースとしてリモート OpenShell ワークスペースを使用します
• workspaceAccess: "ro" と "none" は、引き続き同じ方法で書き込み動作を制限します

受信メディアはアクティブなサンドボックスワークスペース（media/inbound/*）へコピーされます。

カスタムバインドマウント

agents.defaults.sandbox.docker.binds は追加のホストディレクトリをコンテナへマウントします。形式: host:container:mode（例: "/home/user/source:/source:rw"）。

グローバルバインドとエージェントごとのバインドはマージされます（置き換えられません）。scope: "shared" では、エージェントごとのバインドは無視されます。

agents.defaults.sandbox.browser.binds は追加のホストディレクトリをサンドボックスブラウザコンテナにのみマウントします。

• 設定されている場合（[] を含む）、ブラウザコンテナでは agents.defaults.sandbox.docker.binds を置き換えます。
• 省略された場合、ブラウザコンテナは agents.defaults.sandbox.docker.binds にフォールバックします（後方互換）。

例（読み取り専用ソース + 追加データディレクトリ）:

{  agents: {    defaults: {      sandbox: {        docker: {          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],        },      },    },    list: [      {        id: "build",        sandbox: {          docker: {            binds: ["/mnt/cache:/cache:rw"],          },        },      },    ],  },}

イメージとセットアップ

デフォルト Docker イメージ: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN apt-get update && apt-get install -y --no-install-recommends \  bash ca-certificates curl git jq python3 ripgrep \  && rm -rf /var/lib/apt/lists/*RUN useradd --create-home --shell /bin/bash sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

デフォルトでは、Docker サンドボックスコンテナはネットワークなしで実行されます。agents.defaults.sandbox.docker.network で上書きします。

Docker インストールとコンテナ化された Gateway についてはこちらを参照してください: Docker

Docker Gateway デプロイでは、scripts/docker/setup.sh がサンドボックス設定をブートストラップできます。その経路を有効にするには、OPENCLAW_SANDBOX=1（または true/yes/on）を設定します。ソケットの場所は OPENCLAW_DOCKER_SOCKET で上書きできます。完全なセットアップと環境変数リファレンス: Docker。

setupCommand（一度限りのコンテナセットアップ）

setupCommand は、サンドボックスコンテナが作成された後に一度だけ実行されます（毎回の実行時ではありません）。コンテナ内で sh -lc 経由で実行されます。

パス:

• グローバル: agents.defaults.sandbox.docker.setupCommand
• エージェントごと: agents.list[].sandbox.docker.setupCommand

ツールポリシーと回避手段

ツールの許可/拒否ポリシーは、サンドボックスルールより前に引き続き適用されます。ツールがグローバルまたはエージェント単位で拒否されている場合、サンドボックス化しても再び使えるようにはなりません。

tools.elevated は、サンドボックス外で exec を実行する明示的な回避手段です (デフォルトは gateway、exec 対象が node の場合は node)。/exec ディレクティブは、認可された送信者にのみ適用され、セッションごとに永続化されます。exec を完全に無効化するには、ツールポリシーの deny を使用してください (Sandbox vs Tool Policy vs Elevated を参照)。

デバッグ:

• 有効なサンドボックスモード、ツールポリシー、修正用の設定キーを調べるには、openclaw sandbox explain を使用します。
• 「なぜこれがブロックされるのか？」という考え方については、Sandbox vs Tool Policy vs Elevated を参照してください。

厳格にロックダウンした状態を維持してください。

マルチエージェントのオーバーライド

各エージェントは、サンドボックスとツールをオーバーライドできます: agents.list[].sandbox と agents.list[].tools (さらにサンドボックスツールポリシー用の agents.list[].tools.sandbox.tools)。優先順位については、Multi-Agent Sandbox & Tools を参照してください。

最小限の有効化例

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",      },    },  },}

関連項目

• Multi-Agent Sandbox & Tools — エージェントごとのオーバーライドと優先順位
• OpenShell — 管理されたサンドボックスバックエンドのセットアップ、ワークスペースモード、設定リファレンス
• サンドボックス設定
• Sandbox vs Tool Policy vs Elevated — 「なぜこれがブロックされるのか？」のデバッグ
• セキュリティ