サンドボックス

​

サンドボックスの対象となるもの

• ツール実行（exec, read, write, edit, apply_patch, process など）。
• オプションのサンドボックス化されたブラウザ (agents.defaults.sandbox.browser)。
  • デフォルトでは、ブラウザツールが必要になった際に、サンドボックス内のブラウザが自動起動（CDP エンドポイントの疎通確認を含む）します。起動挙動は autoStart や autoStartTimeoutMs で調整可能です。
  • サンドボックスブラウザのコンテナは、デフォルトで専用の Docker ネットワーク (openclaw-sandbox-browser) を使用し、グローバルな bridge ネットワークからは分離されます。
  • cdpSourceRange 設定により、コンテナへの CDP 接続（Ingress）を特定の CIDR 範囲（例: 172.21.0.1/32）に制限できます。
  • noVNC による画面監視は、デフォルトでパスワード保護されます。OpenClaw は短命なトークンを含む URL を発行し、URL フラグメントにパスワードを埋め込んで noVNC を開きます（クエリパラメータやヘッダーログにパスワードが残らないように配慮されています）。
  • allowHostControl を有効にすると、サンドボックス内のセッションから明示的にホスト側のブラウザを操作できるようになります。
  • allowedControlUrls, allowedControlHosts, allowedControlPorts などの許可リストにより、target: "custom" 指定時の接続先を制限できます。

• ゲートウェイプロセス自体。
• ホスト上での実行が明示的に許可されたツール（例: tools.elevated）。
  • 昇格（Elevated）された exec 実行はホスト上で行われ、サンドボックスをバイパスします。
  • サンドボックス機能自体がオフの場合、tools.elevated による挙動の変化はありません（常にホスト上で実行されるため）。詳細は 昇格（Elevated）モード を参照してください。

​

動作モード

• "off": サンドボックスを使用しません。
• "non-main": メイン（main）以外のセッションのみ をサンドボックス化します。ホスト上のファイルを自由に扱いたい通常のチャットはメインセッションで行い、それ以外を制限したい場合のデフォルト設定です。
• "all": すべてのセッションをサンドボックス内で実行します。

​

スコープ (Scope)

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

​

ワークスペースへのアクセス

• "none" (デフォルト): ツールからは ~/.openclaw/sandboxes 配下の専用領域のみが見えます。
• "ro": エージェントのワークスペースを /agent に読み取り専用（read-only）でマウントします。write, edit, apply_patch などの書き込み系ツールは無効化されます。
• "rw": エージェントのワークスペースを /workspace に読み書き可能（read/write）でマウントします。

​

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

• これが設定されている場合（空配列 [] を含む）、ブラウザコンテナにおいては docker.binds の設定を完全に置き換えます。
• 設定されていない（省略された）場合は、通常の 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" と組み合わせてください。バインドモードはそれとは独立して機能します。
• バインドマウントとツールポリシー、および昇格実行の相互作用については、サンドボックス vs ツールポリシー vs 昇格 を参照してください。

​

イメージの作成とセットアップ

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --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-software-rasterizer（コンテナに GPU がない場合に有用。WebGL 等が必要な場合は OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 で無効化可能）
• リソース制限: --renderer-process-limit=2（OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT で調整可能）
• --disable-extensions（拡張機能が必要な場合は OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 で無効化可能）
• その他、バックグラウンド通信やクラッシュレポートの無効化など。

• network: "host" はブロックされます。
• network: "container:<id>" は、ネームスペース共有によるバイパスのリスクがあるため、デフォルトでブロックされます。
• 緊急の上書き設定: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。

​

setupCommand (コンテナの初回セットアップ)

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

• デフォルトの docker.network は "none"（外部通信なし）のため、パッケージのインストールなどは失敗します。
• readOnlyRoot: true の場合、書き込みができません。false に設定するか、あらかじめ必要なものを含めたカスタムイメージを作成してください。
• パッケージインストールには root 権限が必要です（user 設定を省略するか "0:0" に設定）。
• サンドボックス内での実行はホストの process.env を 継承しません。スキルの API キーなどが必要な場合は、agents.defaults.sandbox.docker.env を使用するか、イメージ内に含めてください。

​

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

• openclaw sandbox explain を使用して、現在のサンドボックスモード、適用されているツールポリシー、および修正すべき構成キーを確認してください。
• 「なぜこれがブロックされているのか？」という疑問には、サンドボックス vs ツールポリシー vs 昇格 の考え方が役立ちます。

​

マルチエージェントによる上書き

​

最小限の有効化設定例

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

​

関連ドキュメント

• サンドボックス構成リファレンス
• マルチエージェントにおけるサンドボックスとツール
• セキュリティ