サンドボックス化

​

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

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

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

​

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

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

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

​

Docker バックエンド

​

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

• サンドボックスブラウザーは、ブラウザーツールが必要とするときに自動起動します（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 フラグメント（クエリ文字列やヘッダーログではありません）内のパスワードで noVNC を開く、短命のトークン URL を出力します。
• agents.defaults.sandbox.browser.allowHostControl（デフォルト false）は、サンドボックス化されたセッションがホストブラウザーを明示的にターゲットにできるようにします。
• 任意の許可リストが target: "custom" をゲートします: allowedControlUrls、allowedControlHosts、allowedControlPorts。

​

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" },
        },
      },
    },
  },
}

• ライフサイクル: 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 バックエンド

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

​

ワークスペースアクセス

​

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

{
  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"],
          },
        },
      },
    ],
  },
}

​

イメージとセットアップ

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

​

setupCommand（一度だけのコンテナセットアップ）

• グローバル: agents.defaults.sandbox.docker.setupCommand
• エージェント単位: agents.list[].sandbox.docker.setupCommand

​

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

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

​

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

​

最小有効化例

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

​

関連

• マルチエージェントサンドボックスとツール — エージェントごとの上書きと優先順位
• OpenShell — 管理されたサンドボックスバックエンドのセットアップ、ワークスペースモード、設定リファレンス
• サンドボックス設定
• サンドボックス vs ツールポリシー vs 昇格 — 「なぜこれはブロックされるのか？」のデバッグ
• セキュリティ