​

サンドボックス化

​

何がサンドボックス化されるか

• ツール実行（exec、read、write、edit、apply_patch、process など）。
• 任意のサンドボックス化されたブラウザー（agents.defaults.sandbox.browser）。
  • デフォルトでは、ブラウザーツールが必要とするときにサンドボックスブラウザーが自動起動し（CDPに到達可能であることを保証）、設定は agents.defaults.sandbox.browser.autoStart と agents.defaults.sandbox.browser.autoStartTimeoutMs で行います。
  • デフォルトでは、サンドボックスブラウザーコンテナはグローバルな bridge ネットワークではなく、専用のDockerネットワーク（openclaw-sandbox-browser）を使用します。 agents.defaults.sandbox.browser.network で設定します。
  • 任意の agents.defaults.sandbox.browser.cdpSourceRange では、CIDR allowlist（たとえば 172.21.0.1/32）でコンテナ境界のCDP ingressを制限できます。
  • noVNCのオブザーバーアクセスはデフォルトでパスワード保護されます。OpenClawは短命のトークンURLを発行し、ローカルのブートストラップページを配信して、URLフラグメント内のパスワードでnoVNCを開きます（query/headerログには残りません）。
  • agents.defaults.sandbox.browser.allowHostControl により、サンドボックス化されたセッションが明示的にホストブラウザーを対象にできます。
  • 任意のallowlistで target: "custom" を制御できます: allowedControlUrls、allowedControlHosts、allowedControlPorts。

• Gatewayプロセス自体。
• 明示的にサンドボックス外で実行を許可されたツール（例: tools.elevated）。
  • elevated execはサンドボックス化をバイパスし、設定されたエスケープパス（デフォルトは gateway、execターゲットが node の場合は node）を使用します。
  • サンドボックス化がオフの場合、tools.elevated は実行を変更しません（すでにホスト上です）。Elevated Mode を参照してください。

​

モード

• "off": サンドボックス化しません。
• "non-main": non-main セッションのみサンドボックス化します（通常のチャットをホスト上に残したい場合のデフォルト）。
• "all": すべてのセッションをサンドボックスで実行します。 注: "non-main" はagent idではなく session.mainKey（デフォルト "main"）に基づきます。 グループ/チャネルセッションは独自のキーを使うため、non-mainとして扱われ、サンドボックス化されます。

​

スコープ

• "agent"（デフォルト）: agentごとに1コンテナ。
• "session": sessionごとに1コンテナ。
• "shared": すべてのサンドボックス化セッションで1コンテナを共有。

​

バックエンド

• "docker"（デフォルト）: ローカルDockerベースのサンドボックスランタイム。
• "ssh": 汎用SSHベースのリモートサンドボックスランタイム。
• "openshell": OpenShellベースのサンドボックスランタイム。

​

バックエンドの選択

​

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",
          // または、ローカルファイルの代わりに SecretRef / インライン内容を使います:
          // 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" },
        },
      },
    },
  },
}

• OpenClawは sandbox.ssh.workspaceRoot 配下に、スコープごとのリモートrootを作成します。
• 作成または再作成後の最初の使用時に、OpenClawはローカルワークスペースからそのリモートワークスペースへ一度だけseedします。
• その後、exec、read、write、edit、apply_patch、プロンプトメディア読み取り、および受信メディアのステージングは、SSH経由で直接そのリモートワークスペースに対して実行されます。
• OpenClawは、リモートの変更をローカルワークスペースへ自動同期しません。

• identityFile、certificateFile、knownHostsFile: 既存のローカルファイルを使い、OpenSSH設定を通して渡します。
• identityData、certificateData、knownHostsData: インライン文字列またはSecretRefを使います。OpenClawは通常のsecretsランタイムスナップショット経由でそれらを解決し、0600 で一時ファイルに書き出し、SSHセッション終了時に削除します。
• 同じ項目に対して *File と *Data の両方が設定されている場合、そのSSHセッションでは *Data が優先されます。

• seedステップ後にOpenClaw外で行われたホストローカル編集は、サンドボックスを再作成するまでリモートには反映されません。
• openclaw sandbox recreate はスコープごとのリモートrootを削除し、次回使用時にローカルから再度seedします。
• SSHバックエンドではブラウザーサンドボックス化はサポートされません。
• sandbox.docker.* 設定はSSHバックエンドには適用されません。

​

OpenShellバックエンド

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

• mirror（デフォルト）: ローカルワークスペースが正のままです。OpenClawは exec 前にローカルファイルをOpenShellへ同期し、exec 後にリモートワークスペースをローカルへ同期し戻します。
• remote: サンドボックス作成後はOpenShellワークスペースが正になります。OpenClawはローカルワークスペースから一度だけリモートワークスペースをseedし、その後はファイルツールとexecが変更を戻し同期せずに、直接そのリモートサンドボックスに対して実行されます。

• OpenClawは openshell sandbox ssh-config <name> 経由で、サンドボックス固有のSSH設定をOpenShellに要求します。
• コアはそのSSH設定を一時ファイルに書き出し、SSHセッションを開き、backend: "ssh" で使われるのと同じリモートファイルシステムブリッジを再利用します。
• mirror モードではライフサイクルのみが異なります: exec 前にローカルからリモートへ同期し、その後に同期し戻します。

• サンドボックスブラウザーはまだサポートされていません
• sandbox.docker.binds はOpenShellバックエンドではサポートされていません
• sandbox.docker.* 配下のDocker固有ランタイムノブも、引き続きDockerバックエンドにのみ適用されます

​

ワークスペースモード

mirror

• exec 前に、OpenClawはローカルワークスペースをOpenShellサンドボックスへ同期します。
• exec 後に、OpenClawはリモートワークスペースをローカルワークスペースへ同期し戻します。
• ファイルツールは引き続きサンドボックスブリッジ経由で動作しますが、ターン間ではローカルワークスペースが信頼できる情報源のままです。

• OpenClaw外でローカルにファイルを編集し、その変更を自動的にサンドボックスへ反映させたい
• OpenShellサンドボックスの動作を、できるだけDockerバックエンドに近づけたい
• 各execターン後に、ホストワークスペースへサンドボックスの書き込みを反映させたい

• execの前後に追加の同期コストが発生します

remote

• サンドボックスが最初に作成されるとき、OpenClawはローカルワークスペースからリモートワークスペースへ一度だけseedします。
• その後、exec、read、write、edit、apply_patch は直接リモートOpenShellワークスペースに対して動作します。
• OpenClawは exec 後にリモート変更をローカルワークスペースへ同期し戻しません。
• プロンプト時のメディア読み取りは引き続き動作します。これは、ファイルツールとメディアツールがローカルホストパスを前提にせず、サンドボックスブリッジ経由で読み取るためです。
• トランスポートは、openshell sandbox ssh-config が返すOpenShellサンドボックスへのSSHです。

• seedステップ後にOpenClaw外でホスト上のファイルを編集しても、リモートサンドボックスはそれらの変更を自動では見ません。
• サンドボックスを再作成すると、リモートワークスペースは再びローカルワークスペースからseedされます。
• scope: "agent" または scope: "shared" では、そのリモートワークスペースも同じスコープで共有されます。

• サンドボックスを主にリモートOpenShell側で存続させたい
• ターンごとの同期オーバーヘッドを下げたい
• ホストローカル編集でリモートサンドボックス状態が黙って上書きされることを避けたい

​

OpenShellライフサイクル

• openclaw sandbox list はDockerランタイムだけでなくOpenShellランタイムも表示します
• openclaw sandbox recreate は現在のランタイムを削除し、次回使用時にOpenClawが再作成できるようにします
• pruneロジックもバックエンド対応です

• recreateはそのスコープの正となるリモートワークスペースを削除します
• 次回使用時に、ローカルワークスペースから新しいリモートワークスペースをseedします

​

ワークスペースアクセス

• "none"（デフォルト）: ツールは ~/.openclaw/sandboxes 配下のサンドボックスワークスペースを見ます。
• "ro": agentワークスペースを /agent に読み取り専用でmountします（write/edit/apply_patch を無効化）。
• "rw": agentワークスペースを /workspace に読み書き可能でmountします。

• mirror モードでは、execターン間でもローカルワークスペースが正のソースのままです
• remote モードでは、初回seed後はリモートOpenShellワークスペースが正のソースになります
• workspaceAccess: "ro" と "none" でも、同様に書き込み動作を制限します

​

カスタムBind mounts

• 設定されている場合（[] を含む）、ブラウザーコンテナでは agents.defaults.sandbox.docker.binds を置き換えます。
• 省略されている場合、ブラウザーコンテナは agents.defaults.sandbox.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"],
          },
        },
      },
    ],
  },
}

• bindはサンドボックスファイルシステムを迂回します: 設定したモード（:ro または :rw）でホストパスを公開します。
• OpenClawは危険なbindソース（例: docker.sock、/etc、/proc、/sys、/dev、およびそれらを公開しうる親mount）をブロックします。
• OpenClawは ~/.aws、~/.cargo、~/.config、~/.docker、~/.gnupg、~/.netrc、~/.npm、~/.ssh などの一般的なホームディレクトリ認証情報rootもブロックします。
• bind検証は単なる文字列一致ではありません。OpenClawはソースパスを正規化し、その後で最も深い既存祖先を通して再解決してから、ブロック対象パスと許可rootを再チェックします。
• つまり、最終リーフがまだ存在しなくても、symlink親を使ったエスケープは安全側で失敗します。例: run-link がそこを指している場合、/workspace/run-link/new-file は依然として /var/run/... として解決されます。
• 許可ソースrootも同じ方法で正規化されるため、symlink解決前はallowlist内に見えるだけのパスでも、outside allowed roots として拒否されます。
• 機密性の高いmount（secrets、SSHキー、サービス認証情報）は、絶対に必要でない限り :ro にするべきです。
• ワークスペースへの読み取りアクセスだけが必要なら、workspaceAccess: "ro" と組み合わせてください。bindモードは独立したままです。
• bindとツールポリシーおよびelevated execの相互作用については、Sandbox vs Tool Policy vs Elevated を参照してください。

​

イメージ + セットアップ

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
• --user-data-dir=${HOME}/.chrome
• --no-first-run
• --no-default-browser-check
• --disable-3d-apis
• --disable-gpu
• --disable-dev-shm-usage
• --disable-background-networking
• --disable-extensions
• --disable-features=TranslateUI
• --disable-breakpad
• --disable-crash-reporter
• --disable-software-rasterizer
• --no-zygote
• --metrics-recording-only
• --renderer-process-limit=2
• noSandbox が有効な場合は --no-sandbox と --disable-setuid-sandbox。
• 3つのgraphics hardeningフラグ（--disable-3d-apis、 --disable-software-rasterizer、--disable-gpu）は任意であり、 コンテナにGPUサポートがない場合に有用です。ワークロードでWebGLやその他の3D/ブラウザー機能が必要な場合は、OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 を設定してください。
• --disable-extensions はデフォルトで有効で、拡張機能依存のフローでは OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 で無効化できます。
• --renderer-process-limit=2 は OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> で制御され、0 ではChromiumのデフォルトを維持します。

• network: "host" はブロックされます。
• network: "container:<id>" はデフォルトでブロックされます（namespace joinバイパスのリスク）。
• 緊急時のoverride: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。

​

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

• グローバル: agents.defaults.sandbox.docker.setupCommand
• agentごと: agents.list[].sandbox.docker.setupCommand

• デフォルトの docker.network は "none"（egressなし）なので、パッケージインストールは失敗します。
• docker.network: "container:<id>" には dangerouslyAllowContainerNamespaceJoin: true が必要で、緊急時専用です。
• readOnlyRoot: true は書き込みを防ぎます。readOnlyRoot: false にするか、カスタムイメージを焼いてください。
• パッケージインストールには user がrootである必要があります（user を省略するか、user: "0:0" を設定）。
• サンドボックスexecはホストの process.env を継承しません。SkillのAPIキーには agents.defaults.sandbox.docker.env（またはカスタムイメージ）を使ってください。

​

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

• 有効なサンドボックスモード、ツールポリシー、および修正用設定キーを確認するには openclaw sandbox explain を使用します。
• 「なぜこれがブロックされるのか？」という理解のために、Sandbox vs Tool Policy vs Elevated を参照してください。 制限は厳しく保ってください。

​

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

​

最小の有効化例

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

​

関連ドキュメント

• OpenShell — 管理されたサンドボックスバックエンドのセットアップ、ワークスペースモード、および設定リファレンス
• Sandbox Configuration
• Sandbox vs Tool Policy vs Elevated — 「なぜこれがブロックされるのか？」のデバッグ
• Multi-Agent Sandbox & Tools — agentごとの上書きと優先順位
• Security