サンドボックス化

OpenClaw は、影響範囲を抑えるために サンドボックスバックエンド内でツールを実行できます。これは任意で、設定（agents.defaults.sandbox または agents.list[].sandbox）によって制御されます。サンドボックス化がオフの場合、ツールはホスト上で実行されます。Gateway はホスト上に留まり、ツール実行は有効時に隔離されたサンドボックス内で実行されます。

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

• ツール実行（exec, read, write, edit, apply_patch, process など）。
• 任意のサンドボックス化ブラウザー（agents.defaults.sandbox.browser）。

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

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

# モード

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

# スコープ

agents.defaults.sandbox.scope は、作成されるコンテナ数を制御します:

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

# バックエンド

agents.defaults.sandbox.backend は、サンドボックスを提供するランタイムを制御します:

• "docker"（サンドボックス化が有効な場合のデフォルト）: ローカルの Docker バックエンドのサンドボックスランタイム。
• "ssh": 汎用 SSH バックエンドのリモートサンドボックスランタイム。
• "openshell": OpenShell バックエンドのサンドボックスランタイム。

SSH 固有の設定は agents.defaults.sandbox.ssh 配下にあります。OpenShell 固有の設定は plugins.entries.openshell.config 配下にあります。

# バックエンドの選択

# Docker バックエンド

サンドボックス化はデフォルトでオフです。サンドボックス化を有効にし、バックエンドを選択しない場合、OpenClaw は Docker バックエンドを使用します。Docker デーモンソケット（/var/run/docker.sock）経由で、ツールとサンドボックスブラウザーをローカルで実行します。サンドボックスコンテナの隔離は Docker 名前空間によって決まります。

ホスト GPU を Docker サンドボックスに公開するには、agents.defaults.sandbox.docker.gpus またはエージェントごとの agents.list[].sandbox.docker.gpus オーバーライドを設定します。この値は Docker の --gpus フラグに個別の引数として渡されます。たとえば "all" や "device=GPU-uuid" であり、NVIDIA Container Toolkit などの互換性のあるホストランタイムが必要です。

# SSH バックエンド

任意の SSH でアクセス可能なマシン上で、OpenClaw に 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",
          // Or use SecretRefs / inline contents instead of local files:
          // 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" },
        },
      },
    },
  },
}

# OpenShell バックエンド

OpenShell 管理のリモート環境で OpenClaw にツールをサンドボックス化させたい場合は backend: "openshell" を使用します。完全なセットアップガイド、設定リファレンス、ワークスペースモードの比較については、専用の OpenShell ページ を参照してください。

OpenShell は汎用 SSH バックエンドと同じコア SSH トランスポートおよびリモートファイルシステムブリッジを再利用し、OpenShell 固有のライフサイクル（sandbox create/get/delete, sandbox 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
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
        },
      },
    },
  },
}

OpenShell モード:

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

# ワークスペースモード

OpenShell には 2 つのワークスペースモデルがあります。これは実務上もっとも重要な部分です。

サンドボックスを一時的な実行環境と考える場合は mirror を選びます。サンドボックスを実際のワークスペースと考える場合は remote を選びます。

# OpenShell ライフサイクル

OpenShell サンドボックスは、通常のサンドボックスライフサイクルを通じて引き続き管理されます:

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

remote モードでは、再作成が特に重要です:

• 再作成は、そのスコープの正本であるリモートワークスペースを削除します
• 次回使用時に、ローカルワークスペースから新しいリモートワークスペースがシードされます

mirror モードでは、ローカルワークスペースがいずれにしても正本のままなので、再作成は主にリモート実行環境をリセットします。

# ワークスペースアクセス

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 は、追加のホストディレクトリをサンドボックスブラウザーコンテナだけにマウントします。

• 設定されている場合（[] を含む）、ブラウザーコンテナについて 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"],
          },
        },
      },
    ],
  },
}

# イメージとセットアップ

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

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN 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 sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["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

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

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

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

デバッグ:

• 有効なサンドボックスモード、ツールポリシー、修正用の設定キーを確認するには、openclaw sandbox explain を使用します。
• 「なぜこれがブロックされるのか？」の考え方については、サンドボックス vs ツールポリシー vs Elevated を参照してください。

ロックダウンした状態を維持してください。

# マルチ agent のオーバーライド

各 agent はサンドボックスとツールをオーバーライドできます: agents.list[].sandbox と agents.list[].tools（さらにサンドボックスツールポリシー用の agents.list[].tools.sandbox.tools）。優先順位については、マルチ Agent サンドボックスとツール を参照してください。

# 最小限の有効化例

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

# 関連

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