Sandboxing（サンドボックス化）

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 で設定します。
- agents.defaults.sandbox.browser.allowHostControl は、サンドボックス化されたセッションが明示的にホストブラウザをターゲットにできるようにします。
- オプションの許可リストが target: "custom" をゲートします：allowedControlUrls、allowedControlHosts、allowedControlPorts

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

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

モード

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

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

例（読み取り専用ソース + docker ソケット）：

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

セキュリティ注意事項：

バインドはサンドボックスファイルシステムをバイパスします：設定したモード（:ro または :rw）でホストパスを公開します。
機密マウント（例：docker.sock、シークレット、SSH キー）は、絶対に必要でない限り :ro にする必要があります。
ワークスペースへの読み取りアクセスのみが必要な場合は、workspaceAccess: "ro" と組み合わせてください。バインドモードは独立したままです。
バインドがツールポリシーおよび elevated exec とどのように相互作用するかについては、Sandbox vs Tool Policy vs Elevated を参照してください。

イメージ + セットアップ

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

一度ビルド：

scripts/sandbox-setup.sh

注意：デフォルトイメージには Node が含まれていません。スキルが Node（または他のランタイム）を必要とする場合、カスタムイメージを焼くか、sandbox.docker.setupCommand 経由でインストールしてください（ネットワーク egress + 書き込み可能な root + root ユーザーが必要）。

サンドボックス化されたブラウザイメージ：

scripts/sandbox-browser-setup.sh

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

Docker インストールとコンテナ化された Gateway はこちら：Docker

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

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

パス：

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

よくある落とし穴：

デフォルトの docker.network は "none"（egress なし）なので、パッケージインストールは失敗します。
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 を使用してください（Sandbox vs Tool Policy vs Elevated を参照）。

デバッグ：

openclaw sandbox explain を使用して、有効なサンドボックスモード、ツールポリシー、および修正 config キーを検査します。
「なぜこれがブロックされるのか？」というメンタルモデルについては、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"
      }
    }
  }
}