サンドボックス化

OpenClaw は、影響範囲を縮小するため、サンドボックスバックエンド内でツールを実行できます。サンドボックス化はデフォルトで無効であり、agents.defaults.sandbox（グローバル）または agents.entries.*.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（デフォルト 12s）で設定します。
• サンドボックスブラウザコンテナは、グローバルな 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）を使用すると、サンドボックス化されたセッションからホストブラウザを明示的に対象にできます。
• オプションの許可リストで target: "custom" を制限します：allowedControlUrls、allowedControlHosts、allowedControlPorts。

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/*）にコピーされます。

1 つのエージェントで複数のフォルダを使用する

サンドボックス化された 1 つのエージェントがプライマリワークスペース以外にもアクセスする必要がある場合は、Docker バインドマウントを使用します。各エントリは、明示的なアクセスモードを指定してホストフォルダをコンテナパスに対応付けます。

host-directory:container-directory:rohost-directory:container-directory:rw

• ro は、マウントされたフォルダをサンドボックス内で読み取り専用にします。
• rw は、サンドボックス化されたツールとプロセスによるホストフォルダの変更を許可します。
• コンテナパスは、エージェントが使用するパスです。ホストパスは自動的には公開されません。

次の例では、research エージェントに、書き込み可能なプライマリワークスペース、/reference にある読み取り専用の参考資料、/drafts にある独立した書き込み可能な出力フォルダを提供します。

{  agents: {    defaults: {      sandbox: {        mode: "all",        scope: "agent",      },    },    list: [      {        id: "research",        workspace: "/srv/openclaw/research-workspace",        sandbox: {          workspaceAccess: "rw",          docker: {            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],            // これらのソースはエージェントワークスペース外にあるため必須です。            dangerouslyAllowExternalBindSources: true,          },        },      },    ],  },}

workspaceAccess とバインドモードは独立しています。

workspaceAccess を変更しても、追加のバインドが ro から rw に、またはその逆に変更されることはありません。グローバルとエージェント単位の docker.binds はマージされます。エージェント単位のバインドには scope: "agent" または "session" を維持してください。scope: "shared" はエージェント単位の Docker オーバーライドをすべて無視し、グローバルバインドのみを使用します。

バインドマウントがサポート対象の複数フォルダ境界である理由は、Docker がマウント分離を使用してコンテナのファイルシステムビューを構築し、ro/rw モードがサンドボックス内のすべてのプロセスに適用されるためです。この境界は、OpenClaw の各コードパスでパス認可チェックを重複実装することなく、exec、ファイルシステムツール、子プロセス、ライブラリを対象にします。許可されたシェルまたは依存関係がファイルへ直接アクセスできる場合、ホスト側のパス許可リストでは同等の完全な境界を提供できません。

オプトインの dangerouslyAllowExternalBindSources は、ワークスペースルート外のソースを許可するだけです。OpenClaw によるシステム、認証情報、Docker ソケット、シンボリックリンクの親、予約済みターゲットのブロックチェックを無効にはしません。最小限のフォルダを選び、書き込みが必要でない限り ro を使用し、マウントの変更後はサンドボックスを再作成してください。

openclaw sandbox recreate --agent research

その他のバインド動作

agents.defaults.sandbox.docker.binds はグローバルマウントを設定します。形式は同じ host:container:mode 形式です（例："/home/user/source:/source:rw"）。

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 は、サンドボックスコンテナの作成後に 1 回だけ 実行されます（実行のたびではありません）。コンテナ内で sh -lc を介して実行されます。

パス:

• グローバル: agents.defaults.sandbox.docker.setupCommand
• エージェントごと: agents.entries.*.sandbox.docker.setupCommand

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

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

tools.elevated は、exec をサンドボックス外で実行する明示的なエスケープハッチです（デフォルトでは gateway、exec のターゲットが node の場合は node）。/exec ディレクティブは承認済みの送信者にのみ適用され、セッションごとに保持されます。exec を完全に無効化するには、ツールポリシーで拒否してください（サンドボックス、ツールポリシー、Elevated の比較を参照）。

デバッグ:

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

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

各エージェントは、サンドボックスとツールをオーバーライドできます: agents.entries.*.sandbox および agents.entries.*.tools（さらに、サンドボックスのツールポリシーには agents.entries.*.tools.sandbox.tools）。優先順位については、マルチエージェントのサンドボックスとツールを参照してください。

最小限の有効化例

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

関連項目

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