サンドボックス化

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

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

​

モード

​

スコープ

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

​

バックエンド

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

​

バックエンドの選択

​

Docker バックエンド

​

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 バックエンド

{
  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 はローカルワークスペースからリモートワークスペースを一度シードし、その後ファイルツールと exec は変更を同期して戻さずにリモートサンドボックスに対して直接実行されます。

​

ワークスペースモード

​

OpenShell ライフサイクル

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

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

​

ワークスペースアクセス

• mirror モードでは、exec ターン間の正規ソースとして引き続きローカルワークスペースを使用します
• remote モードでは、初回シード後の正規ソースとしてリモート OpenShell ワークスペースを使用します
• workspaceAccess: "ro" と "none" は、引き続き同じ方法で書き込み動作を制限します

​

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

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

​

イメージとセットアップ

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 explain を使用します。
• 「なぜこれがブロックされるのか？」という考え方については、Sandbox vs Tool Policy vs Elevated を参照してください。

​

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

​

最小限の有効化例

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

​

関連項目

• Multi-Agent Sandbox & Tools — エージェントごとのオーバーライドと優先順位
• OpenShell — 管理されたサンドボックスバックエンドのセットアップ、ワークスペースモード、設定リファレンス
• サンドボックス設定
• Sandbox vs Tool Policy vs Elevated — 「なぜこれがブロックされるのか？」のデバッグ
• セキュリティ