サンドボックス化

OpenClawは、影響範囲を縮小するために、サンドボックスバックエンド内でツールを実行できます。サンドボックス化はデフォルトでは無効で、agents.defaults.sandbox（グローバル）またはagents.list[].sandbox（エージェント単位）で制御します。Gatewayプロセスは常にホスト上に留まり、有効にした場合にツール実行だけがサンドボックスへ移動します。

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

• ツール実行：exec、read、write、edit、apply_patch、processなど。
• オプションのサンドボックス化ブラウザー（agents.defaults.sandbox.browser）。

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

• Gatewayプロセス自体。
• tools.elevatedによってサンドボックス外での実行が明示的に許可されたツール。昇格されたexecはサンドボックス化を迂回し、設定されたエスケープパス（デフォルトはgateway、execターゲットがnodeの場合はnode）で実行されます。サンドボックス化が無効な場合、execはすでにホスト上で実行されるため、tools.elevatedによる変化はありません。昇格モードを参照してください。

モード、スコープ、バックエンド

サンドボックスの動作は、互いに独立した3つの設定で制御します。

モードは、サンドボックス化をいつ適用するかを制御します。

• off：サンドボックス化しません。
• non-main：エージェントのメインセッションを除くすべてのセッションをサンドボックス化します。メインセッションキーは常にagent:<agentId>:main（session.scopeが"global"の場合はglobal）であり、変更できません。グループ／チャンネルセッションは独自のキーを使用するため、常に非メインとして扱われ、サンドボックス化されます。
• all：すべてのセッションをサンドボックス内で実行します。

スコープは、作成するコンテナ／環境の数を制御します。

• agent：エージェントごとに1つのコンテナ。
• session：セッションごとに1つのコンテナ。
• shared：サンドボックス化されたすべてのセッションで1つのコンテナを共有します（このスコープでは、エージェント単位のdocker／ssh／browserオーバーライドは無視されます）。

バックエンドは、サンドボックス化されたツールを実行するランタイムを制御します。SSH固有の設定はagents.defaults.sandbox.sshに、OpenShell固有の設定はplugins.entries.openshell.configにあります。

Dockerバックエンド

サンドボックス化を有効にすると、Dockerがデフォルトのバックエンドになります。Dockerデーモンソケット（/var/run/docker.sock）を介してツールとサンドボックスブラウザーをローカルで実行し、Docker名前空間によって分離します。

デフォルト：network: "none"（外向き通信なし）、readOnlyRoot: true、capDrop: ["ALL"]、イメージopenclaw-sandbox:bookworm-slim。

ホストGPUを公開するには、agents.defaults.sandbox.docker.gpus（またはエージェント単位のオーバーライド）を"all"や"device=GPU-uuid"などの値に設定します。これはDockerの--gpusフラグに渡され、NVIDIA Container Toolkitなど、互換性のあるホストランタイムが必要です。

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

• ブラウザーツールが必要とすると、サンドボックスブラウザーは自動起動します（CDPに到達可能な状態を確保します）。agents.defaults.sandbox.browser.autoStart（デフォルトtrue）およびautoStartTimeoutMs（デフォルト12秒）で設定します。
• サンドボックスブラウザーコンテナは、グローバルな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はローカルのブートストラップページを提供し、URLフラグメントにパスワードを含めてnoVNCを開きます（クエリ文字列やヘッダーログには含めません）。
• agents.defaults.sandbox.browser.allowHostControl（デフォルトfalse）を有効にすると、サンドボックス化されたセッションからホストブラウザーを明示的にターゲットにできます。
• オプションの許可リストallowedControlUrls、allowedControlHosts、allowedControlPortsによって、target: "custom"を制限します。

SSHバックエンド

任意のSSHアクセス可能なマシン上でexec、ファイルツール、メディア読み取りをサンドボックス化するには、backend: "ssh"を使用します。

{  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",          // または、ローカルファイルの代わりにSecretRefs／インライン内容を使用：          // 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" },        },      },    },  },}

デフォルト：command: "ssh"、workspaceRoot: "/tmp/openclaw-sandboxes"、strictHostKeyChecking: true、updateHostKeys: true。

• ライフサイクル：OpenClawは、sandbox.ssh.workspaceRootの下にスコープごとのリモートルートを作成します。作成または再作成後の初回使用時に、ローカルワークスペースからそのリモートワークスペースへ一度だけシードします。その後、exec、read、write、edit、apply_patch、プロンプト内メディアの読み取り、および受信メディアのステージングは、SSH経由でリモートワークスペースに対して直接実行されます。OpenClawはリモートでの変更をローカルワークスペースへ自動的に同期しません。
• 認証情報：identityFile／certificateFile／knownHostsFileは、既存のローカルファイルを参照します。identityData／certificateData／knownHostsDataは、インライン文字列またはSecretRefsを受け入れます。これらは通常のシークレットランタイムスナップショットを介して解決され、モード0600の一時ファイルに書き込まれ、SSHセッション終了時に削除されます。同じ項目に*Fileと*Dataの両方が設定されている場合、そのセッションでは*Dataが優先されます。
• リモートを正とする場合の影響：初回シード後は、リモートSSHワークスペースが実際のサンドボックス状態になります。シード後にOpenClaw外で行ったホストローカルの編集は、サンドボックスを再作成するまでリモートには反映されません。openclaw sandbox recreateはスコープごとのリモートルートを削除し、次回使用時にローカルから再度シードします。このバックエンドではブラウザーのサンドボックス化はサポートされず、sandbox.docker.*設定も適用されません。

OpenShellバックエンド

OpenShellが管理するリモート環境内でツールをサンドボックス化するには、backend: "openshell"を使用します。OpenShellは、汎用SSHバックエンドと同じSSHトランスポートおよびリモートファイルシステムブリッジを再利用し、OpenShellのライフサイクル（sandbox create/get/delete/ssh-config）と、オプションのmirrorワークスペース同期モードを追加します。

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote", // mirror | remote        },      },    },  },}

mode: "mirror"（デフォルト）では、ローカルワークスペースを正として維持します。OpenClawはexecの前にローカルからサンドボックスへ同期し、実行後にサンドボックスからローカルへ同期します。mode: "remote"では、ローカルからリモートワークスペースへ一度だけシードし、その後は同期を戻さずに、リモートワークスペースに対してexec／read／write／edit／apply_patchを直接実行します。シード後のローカル編集は、openclaw sandbox recreateを実行するまで反映されません。scope: "agent"またはscope: "shared"では、そのリモートワークスペースが同じスコープで共有されます。現在の制限：サンドボックスブラウザーはまだサポートされておらず、sandbox.docker.bindsはこのバックエンドには適用されません。

openclaw sandbox list／recreate／pruneはすべて、OpenShellランタイムをDockerランタイムと同様に扱います。pruneロジックはバックエンドを認識します。

完全な前提条件、設定リファレンス、ワークスペースモードの比較、ライフサイクルの詳細については、OpenShellを参照してください。

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

agents.defaults.sandbox.workspaceAccessは、サンドボックスから参照できる範囲を制御します。

OpenShell バックエンドでは、mirror モードは引き続き exec ターン間の正規ソースとしてローカルワークスペースを使用し、remote モードは初回シード後にリモート OpenShell ワークスペースを正規ソースとして使用します。また、workspaceAccess: "ro"/"none" は引き続き同じ方法で書き込み動作を制限します。

受信メディアは、アクティブなサンドボックスワークスペース（media/inbound/*）にコピーされます。

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

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

グローバルとエージェント単位のバインドはマージされます（置換されません）。scope: "shared" では、エージェント単位のバインドは無視されます。

agents.defaults.sandbox.browser.binds は、追加のホストディレクトリを サンドボックスブラウザー コンテナのみにマウントします。設定されている場合（[] を含む）、ブラウザーコンテナでは 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"],          },        },      },    ],  },}

イメージとセットアップ

既定の Docker イメージ：openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN apt-get update && apt-get install -y --no-install-recommends \  bash ca-certificates curl git jq python3 ripgrep \  && rm -rf /var/lib/apt/lists/*RUN useradd --create-home --shell /bin/bash sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

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

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

ツールポリシーと回避手段

ツールの許可／拒否ポリシーは、サンドボックスのルールより先に引き続き適用されます。ツールがグローバルまたはエージェント単位で拒否されている場合、サンドボックス化によって再び利用可能になることはありません。

tools.elevated は、サンドボックス外で exec を実行するための明示的な回避手段です（既定では gateway、exec の対象が node の場合は node）。/exec ディレクティブは許可された送信者にのみ適用され、セッション単位で保持されます。exec を完全に無効化するには、ツールポリシーの deny を使用してください（サンドボックスとツールポリシーと昇格を参照）。

デバッグ：

• openclaw sandbox list は、サンドボックスコンテナ、状態、イメージの一致、経過時間、アイドル時間、関連付けられたセッション／エージェントを表示します。
• openclaw sandbox explain [--session <key>] [--agent <id>] は、有効なサンドボックスモード、ホストワークスペース、ランタイム作業ディレクトリ、Docker マウント、ツールポリシー、修正用の設定キーを調査します。その workspaceRoot フィールドは設定済みのサンドボックスルートのままであり、effectiveHostWorkspaceRoot はアクティブなワークスペースが実際に存在する場所を示します。
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] はコンテナ／環境を削除し、次回使用時に現在の設定で再作成されるようにします。
• 「なぜこれがブロックされるのか」を理解するための考え方については、サンドボックスとツールポリシーと昇格を参照してください。

マルチエージェントの上書き

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

最小限の有効化例

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

関連項目

• マルチエージェントのサンドボックスとツール -- エージェントごとのオーバーライドと優先順位
• OpenShell -- 管理対象サンドボックスバックエンドのセットアップ、ワークスペースモード、設定リファレンス
• サンドボックス設定
• サンドボックスとツールポリシーと昇格の違い -- 「なぜこれがブロックされるのか？」のデバッグ
• セキュリティ