OpenClawのSandboxingでAIエージェントの実行環境を安全に保護する方法

What gets sandboxed

OpenClaw は、モデルが意図しない動作をした際にもファイルシステムやプロセスへのアクセスを制限できるよう、OpenClaw のサンドボックス機能を提供しています。この機能は、以下のツール実行や環境に対して適用されます。

• ツール実行（exec、read、write、edit、apply_patch、process など）。
• オプションのサンドボックス化されたブラウザ（agents.defaults.sandbox.browser）。
  • デフォルトでは、ブラウザツールが必要になった際にサンドボックスブラウザが自動起動し、CDP への到達を保証します。設定は agents.defaults.sandbox.browser.autoStart および agents.defaults.sandbox.browser.autoStartTimeoutMs で行います。
  • デフォルトでは、サンドボックスブラウザのコンテナはグローバルな bridge ネットワークではなく、専用の Docker ネットワーク（openclaw-sandbox-browser）を使用します。設定は agents.defaults.sandbox.browser.network で行います。
  • オプションの agents.defaults.sandbox.browser.cdpSourceRange を使用すると、CIDR 許可リスト（例：172.21.0.1/32）によってコンテナエッジの CDP 受信を制限できます。
  • noVNC のオブザーバーアクセスはデフォルトでパスワード保護されています。OpenClaw は短期間有効なトークン URL を発行し、ローカルのブートストラップページを提供して、URL フラグメント内にパスワードを含めた状態で noVNC を開きます（クエリやヘッダーのログには残りません）。
  • agents.defaults.sandbox.browser.allowHostControl を使用すると、サンドボックス化されたセッションからホストブラウザを明示的にターゲットにできます。
  • target: "custom" を制御するオプションの許可リストとして、allowedControlUrls、allowedControlHosts、allowedControlPorts があります。

以下の項目はサンドボックス化されません。

• Gateway プロセス自体。
• サンドボックス外での実行が明示的に許可されたツール（例：tools.elevated）。
  • Elevated exec はサンドボックスをバイパスし、設定されたエスケープパス（デフォルトは gateway、exec ターゲットが node の場合は node）を使用します。
  • サンドボックスがオフの場合、tools.elevated は実行環境を変更しません（すでにホスト上で実行されているため）。詳細は Elevated Mode を参照してください。

Modes

agents.defaults.sandbox.mode を使用して、OpenClaw のサンドボックスをいつ使用するかを制御します。

• "off": サンドボックスを使用しません。
• "non-main": メイン以外のセッションのみをサンドボックス化します（ホスト上で通常のチャットを行いたい場合のデフォルト設定です）。
• "all": すべてのセッションをサンドボックス内で実行します。 注意: "non-main" はエージェント ID ではなく session.mainKey（デフォルトは "main"）に基づいています。グループやチャンネルのセッションは独自のキーを使用するため、非メインセッションとしてカウントされ、サンドボックス化されます。

Scope

agents.defaults.sandbox.scope を使用して、作成されるコンテナの数を制御します。

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

Backend

agents.defaults.sandbox.backend を使用して、サンドボックスを提供するランタイムを選択します。

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

SSH 固有の設定は agents.defaults.sandbox.ssh に、OpenShell 固有の設定は plugins.entries.openshell.config に記述します。

バックエンドの選択

	Docker	SSH	OpenShell
実行場所	ローカルコンテナ	SSH 接続可能な任意のホスト	OpenShell 管理下のサンドボックス
セットアップ	scripts/sandbox-setup.sh	SSH 鍵 + ターゲットホスト	OpenShell プラグインを有効化
ワークスペース	バインドマウントまたはコピー	リモート正規化（初回シード）	mirror または remote
ネットワーク制御	docker.network（デフォルト: なし）	リモートホストに依存	OpenShell に依存
ブラウザサンドボックス	サポート済み	未サポート	未サポート
バインドマウント	docker.binds	N/A	N/A
推奨用途	ローカル開発、完全な隔離	リモートマシンへのオフロード	双方向同期が可能な管理型リモートサンドボックス

{
  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" },
        },
      },
    },
  },
}

{
  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",
        },
      },
    },
  },
}

Workspace access

agents.defaults.sandbox.workspaceAccess は、sandbox が何を参照できるかを制御する設定です。

1. "none" (デフォルト): ツールは ~/.openclaw/sandboxes 配下の sandbox ワークスペースを参照します。
2. "ro": エージェントのワークスペースを /agent に読み取り専用でマウントします（write、edit、apply_patch は無効化されます）。
3. "rw": エージェントのワークスペースを /workspace に読み書き可能でマウントします。

OpenShell バックエンドを使用する場合の挙動は以下の通りです。

1. mirror モードでは、実行ターンの間でローカルワークスペースが正規のソースとして使用されます。
2. remote モードでは、初期シードの後にリモートの OpenShell ワークスペースが正規のソースとして使用されます。
3. workspaceAccess: "ro" および "none" は、書き込み動作をこれまで通り制限します。

インバウンドのメディアは、アクティブな sandbox ワークスペース（media/inbound/*）にコピーされます。スキルに関する注意点として、read ツールは sandbox をルートとして動作します。workspaceAccess: "none" の場合、OpenClaw は適切なスキルを sandbox ワークスペース（.../skills）にミラーリングするため、それらを読み取ることが可能です。"rw" の場合は、ワークスペース内のスキルを /workspace/skills から読み取ることができます。

Custom bind mounts

agents.defaults.sandbox.docker.binds を使用すると、ホスト側のディレクトリを追加でコンテナ内にマウントできます。形式は host:container:mode です（例: "/home/user/source:/source:rw"）。

グローバルな設定とエージェントごとの設定はマージされ、上書きはされません。scope: "shared" の場合、エージェントごとの設定は無視されます。

agents.defaults.sandbox.browser.binds は、追加のホストディレクトリを sandbox browser コンテナ内にのみマウントします。

1. 設定されている場合（[] を含む）、ブラウザコンテナに対して agents.defaults.sandbox.docker.binds の設定を置き換えます。
2. 省略された場合、ブラウザコンテナは 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"],
          },
        },
      },
    ],
  },
}

セキュリティに関する注意点は以下の通りです。

1. マウントは sandbox のファイルシステムをバイパスするため、設定したモード（:ro または :rw）に応じてホストのパスが公開されます。
2. OpenClaw は危険なマウントソース（例: docker.sock、/etc、/proc、/sys、/dev、およびこれらを公開してしまう親マウント）をブロックします。
3. また、~/.aws、~/.cargo、~/.config、~/.docker、~/.gnupg、~/.netrc、~/.npm、~/.ssh といった、ホームディレクトリ内の一般的な認証情報ルートもブロックされます。
4. マウントの検証は単なる文字列一致ではありません。OpenClaw はソースパスを正規化し、既存の最も深い祖先を通じて再度解決してから、ブロックされたパスや許可されたルートを再チェックします。
5. つまり、シンボリックリンクによる親ディレクトリへの脱出は、最終的な末尾が存在しない場合でも失敗するように設計されています。例えば、run-link が /var/run/... を指している場合、/workspace/run-link/new-file は /var/run/... として解決されます。
6. 許可されたソースルートも同様に正規化されるため、シンボリックリンク解決前に許可リスト内にあるように見えても、実際には outside allowed roots として拒否されます。
7. 機密性の高いマウント（シークレット、SSH キー、サービス認証情報）は、絶対に必要な場合を除き :ro に設定してください。
8. ワークスペースへの読み取りアクセスのみが必要な場合は、workspaceAccess: "ro" と組み合わせてください。マウントモードは独立して機能します。
9. マウントがツールポリシーや権限昇格とどのように相互作用するかについては、Sandbox vs Tool Policy vs Elevated を参照してください。

Docker イメージとセットアップ

OpenClaw の環境構築において、Docker イメージとセットアップは非常に重要な要素です。デフォルトの Docker イメージは openclaw-sandbox:bookworm-slim です。

一度ビルドを実行するには、以下のコマンドを使用します。

scripts/sandbox-setup.sh

注意点として、デフォルトのイメージには Node.js が含まれていません。スキルが Node.js やその他のランタイムを必要とする場合は、カスタムイメージを作成するか、sandbox.docker.setupCommand を介してインストールしてください（これにはネットワークへの出口、書き込み可能なルート、および root ユーザー権限が必要です）。

curl、jq、nodejs、python3、git などの一般的なツールを含む、より機能的なサンドボックスイメージが必要な場合は、以下をビルドしてください。

scripts/sandbox-common-setup.sh

その後、agents.defaults.sandbox.docker.image を openclaw-sandbox-common:bookworm-slim に設定します。

サンドボックス化されたブラウザイメージについては、以下を実行します。

scripts/sandbox-browser-setup.sh

デフォルトでは、Docker サンドボックスコンテナは ネットワークなし で実行されます。変更する場合は agents.defaults.sandbox.docker.network を使用してください。

同梱されているサンドボックスブラウザイメージは、コンテナ化されたワークロード向けに、以下のような控えめな Chromium 起動設定を適用します。

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
• --user-data-dir=${HOME}/.chrome
• --no-first-run
• --no-default-browser-check
• --disable-3d-apis
• --disable-gpu
• --disable-dev-shm-usage
• --disable-background-networking
• --disable-extensions
• --disable-features=TranslateUI
• --disable-breakpad
• --disable-crash-reporter
• --disable-software-rasterizer
• --no-zygote
• --metrics-recording-only
• --renderer-process-limit=2
• --no-sandbox and --disable-setuid-sandbox when noSandbox is enabled.
• The three graphics hardening flags (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) are optional and are useful when containers lack GPU support. Set OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 if your workload requires WebGL or other 3D/browser features.
• --disable-extensions is enabled by default and can be disabled with OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 for extension-reliant flows.
• --renderer-process-limit=2 is controlled by OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>, where 0 keeps Chromium’s default.

異なるランタイムプロファイルが必要な場合は、カスタムブラウザイメージを使用して独自のエントリポイントを提供してください。ローカル（コンテナ外）の Chromium プロファイルについては、browser.extraArgs を使用して起動フラグを追加します。

セキュリティのデフォルト設定は以下の通りです。

• network: "host" はブロックされます。
• network: "container:<id>" は、名前空間結合のバイパスリスクがあるため、デフォルトでブロックされます。
• 緊急時の上書き設定: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true

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

よくある落とし穴は以下の通りです。

• デフォルトの docker.network は "none"（ネットワーク出口なし）であるため、パッケージのインストールは失敗します。
• docker.network: "container:<id>" には dangerouslyAllowContainerNamespaceJoin: true が必要であり、緊急時のみ使用してください。
• readOnlyRoot: true は書き込みを禁止します。readOnlyRoot: false に設定するか、カスタムイメージを作成してください。
• パッケージをインストールするには user が root である必要があります（user を省略するか、user: "0:0" に設定してください）。
• サンドボックスの実行はホストの process.env を継承しません。スキル用の API キーには agents.defaults.sandbox.docker.env（またはカスタムイメージ）を使用してください。

AI Setup Assistant

ツールポリシーとエスケープハッチ

ツールを許可または拒否するポリシーは、サンドボックスのルールよりも先に適用されます。ツールがグローバル設定やエージェント単位の設定で拒否されている場合、サンドボックス環境を有効にしてもそのツールが使用可能になることはありません。

tools.elevated は、サンドボックスの外側で exec を実行するための明示的なエスケープハッチです。デフォルトでは Gateway で実行されますが、実行ターゲットが Node.js の場合は Node.js 上で実行されます。/exec 指令は権限のある送信者にのみ適用され、セッションごとに保持されます。exec を完全に無効化したい場合は、ツールポリシーで拒否設定を行ってください（詳細は Sandbox vs Tool Policy vs Elevated を参照してください）。

デバッグを行う際は、以下の手順を参考にしてください。

1. openclaw sandbox explain コマンドを使用して、有効なサンドボックスモード、ツールポリシー、および修正用設定キーを確認します。
2. 「なぜブロックされているのか？」という疑問については、Sandbox vs Tool Policy vs Elevated を確認して、仕組みを理解するようにしてください。常にセキュリティを強固に保つことが重要です。

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

各エージェントは、サンドボックスやツールの設定を個別に上書きすることが可能です。

agents.list[].sandbox および agents.list[].tools （さらにサンドボックスのツールポリシーについては agents.list[].tools.sandbox.tools）を使用します。優先順位の詳細については、Multi-Agent Sandbox & Tools を参照してください。

最小限の有効化例

OpenClawの最小限の有効化例では、設定ファイルを通じてサンドボックスの動作を制御します。以下の設定を適用することで、エージェントの実行環境を特定のモードに制限し、安全性を確保できます。

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

関連ドキュメント

詳細な設定や概念については、以下のドキュメントを参照してください。

1. OpenShell — 管理されたサンドボックスのバックエンド設定、ワークスペースモード、および設定リファレンス
2. Sandbox Configuration
3. Sandbox vs Tool Policy vs Elevated — 「なぜブロックされるのか」をデバッグするためのガイド
4. Multi-Agent Sandbox & Tools — エージェントごとのオーバーライドと優先順位
5. Security

AI Setup Assistant