サンドボックス化

OpenClaw can run ''tools inside Docker containers'' to reduce blast radius. This is ''optional'' and controlled by configuration (''agents.defaults.sandbox'' or ''agents.list[].sandbox''). If sandboxing is off, tools run on the host.

The Gateway stays on the host; tool execution runs in an isolated sandbox when enabled.

This is not a perfect security boundary, but it materially limits filesystem and process access when the model does something dumb.

ReferenceGatewaySandboxingPage.intro.p4

ReferenceGatewaySandboxingPage.intro.p5

ReferenceGatewaySandboxingPage.intro.p6

ReferenceGatewaySandboxingPage.intro.p7

- ツールの実行（''exec''、''read''、''write''、''edit''、''apply_patch''、''process'' など）。

- オプションのサンドボックスブラウザ（''agents.defaults.sandbox.browser''）。

- By default, the sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it. Configure via ''agents.defaults.sandbox.browser.autoStart'' and ''agents.defaults.sandbox.browser.autoStartTimeoutMs''.

- ''agents.defaults.sandbox.browser.allowHostControl'' lets sandboxed sessions target the host browser explicitly.

- Optional allowlists gate ''target: "custom"'': ''allowedControlUrls'', ''allowedControlHosts'', ''allowedControlPorts''.

- The Gateway process itself.

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

- Any tool explicitly allowed to run on the host (e.g. ''tools.elevated'').

- Elevated exec runs on the host and bypasses sandboxing.

- If sandboxing is off, ''tools.elevated'' does not change execution (already on host). See ''Elevated Mode''.

ReferenceGatewaySandboxingPage.step01.item10

''agents.defaults.sandbox.mode'' はサンドボックスを使用する''タイミング''を制御します：

- ''"off"''：サンドボックスなし。

- ''"non-main"''：''非メイン''セッションのみをサンドボックス化します（ホストで通常のチャットを行いたい場合のデフォルト）。

- ''"all"''：すべてのセッションがサンドボックスで実行されます。

注意：''"non-main"'' はエージェント ID ではなく、''session.mainKey''（デフォルト ''"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'' mounts additional host directories into the container. Format: ''host:container:mode'' (e.g., ''"/home/user/source:/source:rw"'').

Global and per-agent binds are ''merged'' (not replaced). Under ''scope: "shared"'', per-agent binds are ignored.

Example (read-only source + docker socket):

例（読み取り専用ソース+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"],
          },
        },
      },
    ],
  },
}

ReferenceGatewaySandboxingPage.step05.p5

- バインドはサンドボックスファイルシステムを貫通します：設定したモード（'':ro'' または '':rw''）でホストパスを公開します。

- 絶対に必要でない限り、機密性の高いマウント（例：''docker.sock''、シークレット、SSH キー）は '':ro'' にする必要があります。

- ワークスペースへの読み取りアクセスのみが必要な場合は、''workspaceAccess: "ro"'' と組み合わせてください。バインドモードは独立したままです。

- バインドがツールポリシーとエレベートされた実行とどのように相互作用するかについては、''サンドボックス、ツールポリシー、およびエレベート''を参照してください。

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

一度ビルドします：

scripts/sandbox-setup.sh

Note: the default image does ''not'' include Node. If a skill needs Node (or other runtimes), either bake a custom image or install via ''sandbox.docker.setupCommand'' (requires network egress + writable root + root user).

他のランタイム）を必要とする場合、カスタムイメージを焼くか、

''agents.defaults.sandbox.docker.network'' 経由でインストールできます（ネットワークエグレス+書き込み可能なルート+

ルートユーザーが必要です）。

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

scripts/sandbox-browser-setup.sh

ReferenceGatewaySandboxingPage.step06.p8

ReferenceGatewaySandboxingPage.step06.p9

ReferenceGatewaySandboxingPage.step06.p10

''Docker''

''setupCommand'' runs ''once'' after the sandbox container is created (not on every run). It executes inside the container via ''sh -lc''.

Paths:

パス：

- グローバル：''agents.defaults.sandbox.docker.setupCommand''

- エージェントごと：''agents.list[].sandbox.docker.setupCommand''

一般的な落とし穴：

- デフォルトの ''docker.network'' は ''"none"''（エグレスなし）であるため、パッケージのインストールは失敗します。

- ''readOnlyRoot: true'' は書き込みをブロックします。''readOnlyRoot: false'' を設定するか、カスタムイメージを焼きます。

- ''user'' はパッケージインストールのルートである必要があります（''user'' を省略するか、''user: "0:0"'' を設定します）。

- Sandbox exec does ''not'' inherit host ''process.env''. Use ''agents.defaults.sandbox.docker.env'' (or a custom image) for skill API keys.

ツール許可/拒否ポリシーはサンドボックスルールの前に適用されます。ツールが拒否されている場合、

''tools.elevated'' is an explicit escape hatch that runs ''exec'' on the host. ''/exec'' directives only apply for authorized senders and persist per session; to hard-disable ''exec'', use tool policy deny (see ''Sandbox vs Tool Policy vs Elevated'').

Debugging:

Keep it locked down.

ReferenceGatewaySandboxingPage.step08.p5

- ''openclaw sandbox explain'' を使用して、有効なサンドボックスモード、ツールポリシー、修復構成キーを確認します。

- 「なぜブロックされたのか？」のメンタルモデルについては、''サンドボックス、ツールポリシー、およびエレベート''を参照してください。

デバッグ：

Each agent can override sandbox + tools: ''agents.list[].sandbox'' and ''agents.list[].tools'' (plus ''agents.list[].tools.sandbox.tools'' for sandbox tool policy).

See ''Multi-Agent Sandbox & Tools'' for precedence.

- ''サンドボックス構成''

- ''マルチエージェントサンドボックスとツール''

- ''セキュリティ''