サンドボックス化

​

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

• ツールの実行：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）であり、設定できません。グループ／チャンネルセッションは独自のキーを使用するため、常に非メインセッションと見なされ、サンドボックス化されます。
• 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 を発行します。この URL はローカルのブートストラップページを配信し、URL フラグメント（クエリ文字列やヘッダーログではありません）にパスワードを含めて noVNC を開きます。
• 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",
          // または、ローカルファイルの代わりに 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" },
        },
      },
    },
  },
}

• ライフサイクル：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
        },
      },
    },
  },
}

​

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

​

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

host-directory:container-directory:ro
host-directory:container-directory:rw

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

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

openclaw sandbox recreate --agent research

​

その他のバインド動作

{
  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.entries.*.sandbox.docker.setupCommand

​

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

• 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: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

​

関連項目

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