サンドボックス

OpenClaw は影響範囲を縮小するためにツールを Docker コンテナ内で実行できます。 これは任意機能であり、設定（agents.defaults.sandbox または agents.list[].sandbox）で制御されます。サンドボックスがオフの場合、ツールはホスト上で直接実行されます。 Gateway はホスト上に留まり、有効時にはツール実行が分離されたサンドボックス内で行われます。

完璧なセキュリティ境界ではありませんが、モデルが不適切な操作を行った場合のファイルシステムおよびプロセスへのアクセスを実質的に制限します。

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

  • ツール実行（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 許可リストによるコンテナエッジの CDP イングレス制限が可能です（例：172.21.0.1/32）。
    • noVNC オブザーバーアクセスはデフォルトでパスワード保護されています。OpenClaw は短期間有効なトークン URL を発行し、ローカルブートストラップページを配信して URL フラグメント（クエリ/ヘッダーログではなく）にパスワードを含めて noVNC を開きます。
    • agents.defaults.sandbox.browser.allowHostControl で、サンドボックスセッションからホストブラウザを明示的にターゲットできます。
    • オプションの許可リストが target: "custom" をゲートします：allowedControlUrls、allowedControlHosts、allowedControlPorts。

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

  • Gateway プロセス自体。
  • ホスト上で実行が明示的に許可されたツール（例：tools.elevated）。
    • Elevated exec はホスト上で実行され、サンドボックスをバイパスします。
    • サンドボックスがオフの場合、tools.elevated は実行を変更しません（すでにホスト上）。詳細は Elevated モード を参照。

モード

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

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

スコープ

agents.defaults.sandbox.scope はコンテナの数を制御します：

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

ワークスペースアクセス

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

  • "none"（デフォルト）：ツールは ~/.openclaw/sandboxes 配下のサンドボックスワークスペースを参照。
  • "ro"：エージェントワークスペースを /agent に読み取り専用でマウント（write/edit/apply_patch は無効化）。
  • "rw"：エージェントワークスペースを /workspace に読み書き可能でマウント。

受信メディアはアクティブなサンドボックスワークスペース（media/inbound/*）にコピーされます。 スキルに関する注意：read ツールはサンドボックスルートを基準にします。workspaceAccess: "none" の場合、OpenClaw は対象スキルをサンドボックスワークスペース（.../skills）にミラーリングして読み取り可能にします。"rw" の場合、ワークスペースのスキルは /workspace/skills から読み取れます。

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

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

セキュリティ上の注意：

  • バインドはサンドボックスのファイルシステムをバイパスします。設定したモード（:ro または :rw）でホストパスが公開されます。
  • OpenClaw は危険なバインドソース（例：docker.sock、/etc、/proc、/sys、/dev、およびこれらを含む親マウント）をブロックします。
  • 機密マウント（シークレット、SSH キー、サービス資格情報）は絶対に必要な場合を除き :ro にしてください。
  • ワークスペースへの読み取りアクセスだけが必要な場合は workspaceAccess: "ro" と組み合わせてください。バインドモードは独立して維持されます。
  • バインドとツールポリシーおよび elevated exec の関係については サンドボックス vs ツールポリシー vs Elevated を参照してください。

イメージとセットアップ

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

初回ビルド：

scripts/sandbox-setup.sh

注意：デフォルトイメージには Node が含まれていません。スキルが Node（やその他のランタイム）を必要とする場合は、カスタムイメージをビルドするか、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

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

同梱のサンドボックスブラウザイメージは、コンテナ化されたワークロード向けに保守的な Chromium 起動デフォルトも適用します。現在のコンテナデフォルトは以下を含みます：

  • --remote-debugging-address=127.0.0.1
  • --remote-debugging-port=<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
  • noSandbox が有効な場合は --no-sandbox と --disable-setuid-sandbox。
  • 3つのグラフィックスハードニングフラグ（--disable-3d-apis、--disable-software-rasterizer、--disable-gpu）はオプションで、コンテナが GPU サポートを持たない場合に有用です。WebGL やその他の 3D/ブラウザ機能が必要な場合は OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 を設定してください。
  • --disable-extensions はデフォルトで有効です。拡張機能が必要なフローでは OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 で無効化できます。
  • --renderer-process-limit=2 は OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> で制御します。0 で Chromium のデフォルトを維持します。

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

セキュリティデフォルト：

  • network: "host" はブロックされます。
  • network: "container:<id>" はデフォルトでブロックされます（名前空間結合バイパスのリスク）。
  • 緊急回避オーバーライド：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。

Docker のインストールとコンテナ化された Gateway については： Docker

Docker Gateway デプロイでは、docker-setup.sh でサンドボックス設定をブートストラップできます。 OPENCLAW_SANDBOX=1（または true/yes/on）を設定してそのパスを有効化してください。 ソケットの場所は OPENCLAW_DOCKER_SOCKET で上書きできます。完全なセットアップと env のリファレンス：Docker。

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

setupCommand はサンドボックスコンテナ作成後に1回だけ実行されます（毎回ではありません）。 コンテナ内で 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" を設定）。
  • サンドボックス exec はホストの process.env を継承しません。スキルの API キーには agents.defaults.sandbox.docker.env（またはカスタムイメージ）を使用してください。

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

ツール許可/拒否ポリシーはサンドボックスルールの前に適用されます。グローバルまたはエージェントごとにツールが拒否されている場合、サンドボックスでそれを復活させることはできません。

tools.elevated はホスト上で exec を実行する明示的なエスケープハッチです。 /exec ディレクティブは権限のある送信者にのみ適用され、セッションごとに永続化されます。exec を完全に無効化するにはツールポリシーの deny を使用してください（サンドボックス vs ツールポリシー vs Elevated を参照）。

デバッグ：

  • openclaw sandbox explain で有効なサンドボックスモード、ツールポリシー、修正設定キーを確認できます。
  • 「なぜブロックされているのか」のメンタルモデルについては サンドボックス vs ツールポリシー vs Elevated を参照してください。 セキュリティは厳しく保ちましょう。

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

各エージェントはサンドボックスとツールを個別に上書きできます： agents.list[].sandbox と agents.list[].tools（サンドボックスツールポリシーには agents.list[].tools.sandbox.tools）。 優先順位の詳細は マルチエージェント サンドボックス & ツール を参照してください。

最小限の有効化例

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

関連ドキュメント

arrow_back
前へ
Security
次へ
Sandbox Vs Tool Policy Vs Elevated
arrow_forward