Docker（任意）

Docker は任意です。コンテナ化された Gateway が必要な場合、または Docker フローの検証が必要な場合にのみ使用してください。

Docker は自分に向いているか？

はい：分離された使い捨ての Gateway 環境が欲しい場合、またはローカルインストールなしのホストで OpenClaw を実行したい場合。
いいえ：自分のマシンで最速の開発ループが欲しい場合。通常のインストールフローを使ってください。
サンドボックスに関する注意：エージェントサンドボックスも Docker を使用しますが、Gateway 全体を Docker で実行する必要はありません。サンドボックスを参照。

このガイドの内容：

コンテナ化 Gateway（フル OpenClaw を Docker で実行）
セッションごとのエージェントサンドボックス（ホスト Gateway + Docker 分離エージェントツール）

サンドボックスの詳細：サンドボックス

要件

Docker Desktop（または Docker Engine） + Docker Compose v2
イメージビルド用に最低 2 GB RAM（pnpm install は 1 GB ホストでは exit 137 で OOM-killed される可能性あり）
イメージ + ログ用の十分なディスク容量
VPS/パブリックホストで実行する場合は、ネットワーク公開のセキュリティハードニング、特に Docker の DOCKER-USER ファイアウォールポリシーを確認してください。

コンテナ化 Gateway（Docker Compose）

クイックスタート（推奨）

注意： ここでの Docker デフォルトはバインドモード（lan/loopback）を前提としており、ホストエイリアスではありません。gateway.bind にはバインドモード値（例：lan や loopback）を使用し、0.0.0.0 や localhost のようなホストエイリアスは使わないでください。

リポジトリルートから：

./docker-setup.sh

このスクリプトは：

Gateway イメージをローカルでビルド（または OPENCLAW_IMAGE が設定されている場合はリモートイメージをプル）
オンボーディングウィザードを実行
任意のプロバイダーセットアップのヒントを表示
Docker Compose で Gateway を起動
Gateway トークンを生成し .env に書き込み

任意の環境変数：

OPENCLAW_IMAGE — ローカルビルドの代わりにリモートイメージを使用（例：ghcr.io/openclaw/openclaw:latest）
OPENCLAW_DOCKER_APT_PACKAGES — ビルド時に追加の apt パッケージをインストール
OPENCLAW_EXTENSIONS — ビルド時にエクステンションの依存関係を事前インストール（スペース区切りのエクステンション名、例：diagnostics-otel matrix）
OPENCLAW_EXTRA_MOUNTS — ホストバインドマウントを追加
OPENCLAW_HOME_VOLUME — /home/node を名前付きボリュームで永続化
OPENCLAW_SANDBOX — Docker Gateway サンドボックスのブートストラップをオプトイン。明示的な truthy 値のみ有効：1、true、yes、on
OPENCLAW_INSTALL_DOCKER_CLI — ローカルイメージビルド用のビルド引数パススルー（1 でイメージ内に Docker CLI をインストール）。docker-setup.sh はローカルビルドで OPENCLAW_SANDBOX=1 の場合に自動設定。
OPENCLAW_DOCKER_SOCKET — Docker ソケットパスのオーバーライド（デフォルト：DOCKER_HOST=unix://... パス、それ以外は /var/run/docker.sock）
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 — ブレークグラス：CLI/オンボーディングクライアントパスで信頼済みプライベートネットワークの ws:// ターゲットを許可（デフォルトはループバックのみ）
OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 — WebGL/3D 互換性が必要な場合にコンテナブラウザのハードニングフラグ --disable-3d-apis、--disable-software-rasterizer、--disable-gpu を無効化。
OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 — ブラウザフローでエクステンションが必要な場合にエクステンションを有効に保持（デフォルトではサンドボックスブラウザでエクステンション無効）。
OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> — Chromium レンダラープロセス制限を設定。0 でフラグをスキップし、Chromium デフォルト動作を使用。

完了後：

ブラウザで http://127.0.0.1:18789/ を開く。
コントロール UI にトークンを貼り付け（設定 → トークン）。
URL が再度必要な場合は docker compose run --rm openclaw-cli dashboard --no-open を実行。

Docker Gateway 用エージェントサンドボックスの有効化（オプトイン）

docker-setup.sh は Docker デプロイ向けに agents.defaults.sandbox.* もブートストラップできます。

有効にするには：

export OPENCLAW_SANDBOX=1
./docker-setup.sh

カスタムソケットパス（例：ルートレス Docker）：

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./docker-setup.sh

注意事項：

スクリプトはサンドボックスの前提条件が通過した後にのみ docker.sock をマウントします。
サンドボックスセットアップが完了できない場合、スクリプトは再実行時の古い/壊れたサンドボックス設定を避けるため agents.defaults.sandbox.mode を off にリセットします。
Dockerfile.sandbox が見つからない場合、スクリプトは警告を表示して続行します。必要に応じて scripts/sandbox-setup.sh で openclaw-sandbox:bookworm-slim をビルドしてください。
非ローカルの OPENCLAW_IMAGE 値の場合、イメージはサンドボックス実行のために Docker CLI サポートを既に含んでいる必要があります。

自動化/CI（非対話、TTY ノイズなし）

スクリプトや CI では、-T で Compose の擬似 TTY 割り当てを無効化：

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

自動化が Claude セッション変数をエクスポートしない場合、未設定のままでも docker-compose.yml でデフォルトで空の値に解決されるため、繰り返しの「variable is not set」警告が回避されます。

共有ネットワークのセキュリティに関する注意（CLI + Gateway）

openclaw-cli は network_mode: "service:openclaw-gateway" を使用し、Docker 内で CLI コマンドが 127.0.0.1 経由で確実に Gateway に到達できるようにしています。

これは共有信頼境界として扱ってください。ループバックバインディングはこれら 2 つのコンテナ間の分離ではありません。より強い分離が必要な場合は、バンドルされた openclaw-cli サービスの代わりに、別のコンテナ/ホストネットワークパスからコマンドを実行してください。

CLI プロセスが侵害された場合の影響を軽減するため、compose 設定は openclaw-cli で NET_RAW/NET_ADMIN をドロップし、no-new-privileges を有効にしています。

ホスト上に設定/ワークスペースを書き込みます：

~/.openclaw/
~/.openclaw/workspace

VPS で実行する場合は Hetzner（Docker VPS）を参照。

リモートイメージの使用（ローカルビルドをスキップ）

公式のプリビルトイメージの公開先：

GitHub Container Registry パッケージ

イメージ名 ghcr.io/openclaw/openclaw を使用してください（同名の Docker Hub イメージではありません）。

主なタグ：

main — main からの最新ビルド
<version> — リリースタグビルド（例：2026.2.26）
latest — 最新の安定リリースタグ

ベースイメージのメタデータ

メインの Docker イメージが現在使用しているもの：

node:24-bookworm

Docker イメージは OCI ベースイメージアノテーションを公開するようになりました（sha256 は例であり、そのタグのピン留めされたマルチアーキテクチャマニフェストリストを指します）：

org.opencontainers.image.base.name=docker.io/library/node:24-bookworm
org.opencontainers.image.base.digest=sha256:3a09aa6354567619221ef6c45a5051b671f953f0a1924d1f819ffb236e520e6b
org.opencontainers.image.source=https://github.com/openclaw/openclaw
org.opencontainers.image.url=https://openclaw.ai
org.opencontainers.image.documentation=https://docs.openclaw.ai/install/docker
org.opencontainers.image.licenses=MIT
org.opencontainers.image.title=OpenClaw
org.opencontainers.image.description=OpenClaw gateway and CLI runtime container image
org.opencontainers.image.revision=<git-sha>
org.opencontainers.image.version=<tag-or-main>
org.opencontainers.image.created=<rfc3339 timestamp>

参考：OCI イメージアノテーション

リリースコンテキスト：このリポジトリのタグ付き履歴では、v2026.2.22 以前の 2026 タグ（例：v2026.2.21、v2026.2.9）で既に Bookworm を使用しています。

デフォルトではセットアップスクリプトがソースからイメージをビルドします。プリビルトイメージをプルするには、スクリプト実行前に OPENCLAW_IMAGE を設定してください：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

スクリプトは OPENCLAW_IMAGE がデフォルトの openclaw:local でないことを検出し、docker build の代わりに docker pull を実行します。それ以外（オンボーディング、Gateway 起動、トークン生成）は同じように動作します。

docker-setup.sh はローカルの docker-compose.yml とヘルパーファイルを使用するため、リポジトリルートから実行する必要があります。OPENCLAW_IMAGE はローカルイメージのビルド時間をスキップするだけで、compose/セットアップワークフロー自体を置き換えるものではありません。

シェルヘルパー（任意）

日常の Docker 管理を楽にするために、ClawDock をインストール：

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

シェル設定に追加（zsh）：

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

clawdock-start、clawdock-stop、clawdock-dashboard などを使用できます。clawdock-help ですべてのコマンドを確認してください。

詳細は ClawDock ヘルパー README を参照。

手動フロー（compose）

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

docker compose ... はリポジトリルートから実行してください。OPENCLAW_EXTRA_MOUNTS や OPENCLAW_HOME_VOLUME を有効にした場合、セットアップスクリプトが docker-compose.extra.yml を書き込みます。別の場所で Compose を実行する場合はそれを含めてください：

docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

コントロール UI トークン + ペアリング（Docker）

「unauthorized」や「disconnected (1008): pairing required」が表示される場合は、新しいダッシュボードリンクを取得してブラウザデバイスを承認してください：

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

詳細：ダッシュボード、デバイス。

追加マウント（任意）

ホストディレクトリを追加でコンテナにマウントする場合は、docker-setup.sh 実行前に OPENCLAW_EXTRA_MOUNTS を設定してください。カンマ区切りの Docker バインドマウントリストを受け付け、docker-compose.extra.yml を生成して openclaw-gateway と openclaw-cli の両方に適用します。

例：

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

注意事項：

macOS/Windows では、パスが Docker Desktop と共有されている必要があります。
各エントリは source:target[:options] で、スペース、タブ、改行を含まないこと。
OPENCLAW_EXTRA_MOUNTS を変更した場合は、docker-setup.sh を再実行して extra compose ファイルを再生成してください。
docker-compose.extra.yml は自動生成されたファイルです。手動で編集しないでください。

コンテナホーム全体の永続化（任意）

/home/node をコンテナ再作成後も永続化したい場合は、OPENCLAW_HOME_VOLUME で名前付きボリュームを設定してください。Docker ボリュームを作成して /home/node にマウントしつつ、標準の設定/ワークスペースバインドマウントは維持されます。ここでは名前付きボリュームを使用してください（バインドパスではなく）。バインドマウントには OPENCLAW_EXTRA_MOUNTS を使用してください。

例：

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

追加マウントとの組み合わせも可能：

export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

注意事項：

名前付きボリュームは ^[A-Za-z0-9][A-Za-z0-9_.-]*$ に一致する必要があります。
OPENCLAW_HOME_VOLUME を変更した場合は、docker-setup.sh を再実行して extra compose ファイルを再生成してください。
名前付きボリュームは docker volume rm <name> で削除するまで保持されます。

追加 apt パッケージのインストール（任意）

イメージ内にシステムパッケージ（ビルドツールやメディアライブラリなど）が必要な場合は、docker-setup.sh 実行前に OPENCLAW_DOCKER_APT_PACKAGES を設定してください。イメージビルド時にパッケージがインストールされるため、コンテナが削除されても保持されます。

例：

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

注意事項：

スペース区切りの apt パッケージ名リストを受け付けます。
OPENCLAW_DOCKER_APT_PACKAGES を変更した場合は、docker-setup.sh を再実行してイメージを再ビルドしてください。

エクステンション依存関係の事前インストール（任意）

独自の package.json を持つエクステンション（例：diagnostics-otel、matrix、msteams）は初回ロード時に npm 依存関係をインストールします。それらの依存関係をイメージに組み込むには、docker-setup.sh 実行前に OPENCLAW_EXTENSIONS を設定してください：

export OPENCLAW_EXTENSIONS="diagnostics-otel matrix"
./docker-setup.sh

直接ビルドする場合：

docker build --build-arg OPENCLAW_EXTENSIONS="diagnostics-otel matrix" .

注意事項：

スペース区切りのエクステンションディレクトリ名（extensions/ 配下）を受け付けます。
package.json を持つエクステンションのみ影響されます。持たない軽量プラグインは無視されます。
OPENCLAW_EXTENSIONS を変更した場合は、docker-setup.sh を再実行してイメージを再ビルドしてください。

パワーユーザー / フル機能コンテナ（オプトイン）

デフォルトの Docker イメージはセキュリティファーストであり、非 root の node ユーザーとして実行されます。攻撃対象領域を小さく保ちますが、以下を意味します：

ランタイムでのシステムパッケージインストール不可
デフォルトでは Homebrew なし
バンドルされた Chromium/Playwright ブラウザなし

より高機能なコンテナが必要な場合は、以下のオプトインノブを使用してください：

/home/node の永続化でブラウザのダウンロードやツールキャッシュを維持：

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

システム依存関係をイメージに組み込み（再現可能 + 永続的）：

export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh

npx なしで Playwright ブラウザをインストール（npm オーバーライドの競合を回避）：

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

Playwright でシステム依存関係のインストールが必要な場合は、ランタイムで --with-deps を使用する代わりに OPENCLAW_DOCKER_APT_PACKAGES でイメージを再ビルドしてください。

Playwright ブラウザのダウンロードを永続化：

docker-compose.yml で PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright を設定。
OPENCLAW_HOME_VOLUME で /home/node を永続化するか、OPENCLAW_EXTRA_MOUNTS で /home/node/.cache/ms-playwright をマウント。

パーミッション + EACCES

イメージは node（uid 1000）として実行されます。/home/node/.openclaw でパーミッションエラーが発生する場合は、ホストのバインドマウントが uid 1000 で所有されていることを確認してください。

例（Linux ホスト）：

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

利便性のため root で実行することを選択した場合、セキュリティ上のトレードオフを受け入れることになります。

より高速なリビルド（推奨）

リビルドを高速化するには、依存関係レイヤーがキャッシュされるよう Dockerfile を構成してください。ロックファイルが変更されない限り pnpm install の再実行を回避できます：

FROM node:24-bookworm

# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Cache dependencies unless package metadata changes
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

チャンネルセットアップ（任意）

CLI コンテナを使ってチャンネルを設定し、必要に応じて Gateway を再起動します。

WhatsApp（QR）：

docker compose run --rm openclaw-cli channels login

Telegram（ボットトークン）：

docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

Discord（ボットトークン）：

docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

ドキュメント：WhatsApp、Telegram、Discord

OpenAI Codex OAuth（ヘッドレス Docker）

ウィザードで OpenAI Codex OAuth を選択すると、ブラウザ URL が開かれ、http://127.0.0.1:1455/auth/callback でコールバックのキャプチャが試みられます。Docker やヘッドレス環境ではコールバックがブラウザエラーを表示する場合があります。リダイレクト先の完全な URL をコピーし、ウィザードに貼り付けて認証を完了してください。

ヘルスチェック

コンテナプローブエンドポイント（認証不要）：

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

エイリアス：/health と /ready。

/healthz は「Gateway プロセスが起動しているか」のシャローなライブネスプローブです。 /readyz は起動猶予期間中は ready を維持し、猶予期間後に必須のマネージドチャンネルがまだ切断されている場合、または後で切断された場合にのみ 503 を返します。

Docker イメージにはバックグラウンドで /healthz を ping する組み込み HEALTHCHECK が含まれています。つまり Docker が OpenClaw の応答性を継続的にチェックしています。チェックが続けて失敗すると、Docker はコンテナを unhealthy とマークし、オーケストレーションシステム（Docker Compose の restart ポリシー、Swarm、Kubernetes など）が自動的に再起動または置き換えできます。

認証付きの詳細ヘルススナップショット（Gateway + チャンネル）：

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

E2E スモークテスト（Docker）

scripts/e2e/onboard-docker.sh

QR インポートスモークテスト（Docker）

pnpm test:docker:qr

LAN vs ループバック（Docker Compose）

docker-setup.sh はデフォルトで OPENCLAW_GATEWAY_BIND=lan を設定し、Docker のポートパブリッシングでホストから http://127.0.0.1:18789 へのアクセスが機能するようにしています。

lan（デフォルト）：ホストブラウザ + ホスト CLI がパブリッシュされた Gateway ポートに到達可能。
loopback：コンテナネットワーク名前空間内のプロセスのみが Gateway に直接到達可能。ホストパブリッシュされたポートアクセスは失敗する場合あり。

セットアップスクリプトはオンボーディング後に gateway.mode=local もピン留めし、Docker CLI コマンドがデフォルトでローカルループバックターゲットを使用するようにします。

レガシー設定の注意：gateway.bind にはバインドモード値（lan / loopback / custom / tailnet / auto）を使用し、ホストエイリアス（0.0.0.0、127.0.0.1、localhost、::、::1）は使わないでください。

Docker CLI コマンドで Gateway target: ws://172.x.x.x:18789 や繰り返しの pairing required エラーが表示される場合：

docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

注意事項

コンテナ使用時の Gateway バインドはデフォルトで lan（OPENCLAW_GATEWAY_BIND）。
Dockerfile の CMD は --allow-unconfigured を使用。gateway.mode が local でないマウント済み設定でも起動します。ガードを強制するには CMD をオーバーライドしてください。
Gateway コンテナがセッションの正です（~/.openclaw/agents/<agentId>/sessions/）。

ストレージモデル

**永続ホストデータ：**Docker Compose は OPENCLAW_CONFIG_DIR を /home/node/.openclaw に、OPENCLAW_WORKSPACE_DIR を /home/node/.openclaw/workspace にバインドマウントするため、コンテナ置き換え後も存続します。
エフェメラルサンドボックス tmpfs：agents.defaults.sandbox が有効な場合、サンドボックスコンテナは /tmp、/var/tmp、/run に tmpfs を使用します。これらのマウントはトップレベルの Compose スタックとは別で、サンドボックスコンテナとともに消失します。
ディスク増加のホットスポット：media/、agents/<agentId>/sessions/sessions.json、トランスクリプト JSONL ファイル、cron/runs/*.jsonl、/tmp/openclaw/（または設定した logging.file）配下のローリングファイルログを監視してください。Docker 外で macOS アプリも実行している場合、そのサービスログは別です：~/.openclaw/logs/gateway.log、~/.openclaw/logs/gateway.err.log、/tmp/openclaw/openclaw-gateway.log。

エージェントサンドボックス（ホスト Gateway + Docker ツール）

詳細：サンドボックス

仕組み

agents.defaults.sandbox が有効な場合、非メインセッションのツールは Docker コンテナ内で実行されます。Gateway はホスト上に留まりますが、ツール実行は分離されます：

スコープ：デフォルトで "agent"（エージェントごとに 1 コンテナ + ワークスペース）
スコープ："session" でセッションごとの分離
スコープごとのワークスペースフォルダが /workspace にマウント
任意のエージェントワークスペースアクセス（agents.defaults.sandbox.workspaceAccess）
許可/拒否のツールポリシー（拒否が優先）
受信メディアはアクティブなサンドボックスワークスペース（media/inbound/*）にコピーされ、ツールが読み取り可能（workspaceAccess: "rw" の場合、エージェントワークスペースに配置）

注意：scope: "shared" はクロスセッション分離を無効化します。すべてのセッションが 1 つのコンテナと 1 つのワークスペースを共有します。

エージェントごとのサンドボックスプロファイル（マルチエージェント）

マルチエージェントルーティングを使用する場合、各エージェントはサンドボックス + ツール設定をオーバーライドできます： agents.list[].sandbox と agents.list[].tools（+ agents.list[].tools.sandbox.tools）。1 つの Gateway で異なるアクセスレベルを混在させることができます：

フルアクセス（個人エージェント）
読み取り専用ツール + 読み取り専用ワークスペース（家族/仕事エージェント）
ファイルシステム/シェルツールなし（パブリックエージェント）

例、優先順位、トラブルシューティングについてはマルチエージェントサンドボックス＆ツールを参照。

デフォルト動作

イメージ：openclaw-sandbox:bookworm-slim
エージェントごとに 1 コンテナ
エージェントワークスペースアクセス：workspaceAccess: "none"（デフォルト）は ~/.openclaw/sandboxes を使用
- "ro" はサンドボックスワークスペースを /workspace に保持し、エージェントワークスペースを /agent に読み取り専用マウント（write/edit/apply_patch を無効化）
- "rw" はエージェントワークスペースを /workspace に読み書きマウント
自動プルーニング：アイドル > 24 時間 OR 経過日数 > 7 日
ネットワーク：デフォルトで none（外向きが必要な場合は明示的にオプトイン）
- host はブロック。
- container:<id> はデフォルトでブロック（名前空間結合リスク）。
デフォルト許可：exec、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
デフォルト拒否：browser、canvas、nodes、cron、discord、gateway

サンドボックスの有効化

setupCommand でパッケージをインストールする場合の注意事項：

デフォルトの docker.network は "none"（外向き通信なし）。
docker.network: "host" はブロック。
docker.network: "container:<id>" はデフォルトでブロック。
ブレークグラスオーバーライド：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。
readOnlyRoot: true はパッケージインストールをブロック。
apt-get には user が root である必要あり（user を省略するか user: "0:0" を設定）。 OpenClaw は setupCommand（または docker 設定）が変更されたとき、コンテナが最近使用された（約 5 分以内）場合を除き、コンテナを自動再作成します。ホットコンテナは正確な openclaw sandbox recreate ... コマンドを含む警告をログに出力します。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24, // 0 disables idle pruning
          maxAgeDays: 7, // 0 disables max-age pruning
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

ハードニングノブは agents.defaults.sandbox.docker 配下にあります： network、user、pidsLimit、memory、memorySwap、cpus、ulimits、 seccompProfile、apparmorProfile、dns、extraHosts、 dangerouslyAllowContainerNamespaceJoin（ブレークグラスのみ）。

マルチエージェント：agents.defaults.sandbox.{docker,browser,prune}.* をエージェントごとに agents.list[].sandbox.{docker,browser,prune}.* でオーバーライド可能（agents.defaults.sandbox.scope / agents.list[].sandbox.scope が "shared" の場合は無視）。

デフォルトサンドボックスイメージのビルド

scripts/sandbox-setup.sh

Dockerfile.sandbox を使って openclaw-sandbox:bookworm-slim をビルドします。

サンドボックス共通イメージ（任意）

一般的なビルドツール（Node、Go、Rust など）を含むサンドボックスイメージが必要な場合は、共通イメージをビルドしてください：

scripts/sandbox-common-setup.sh

openclaw-sandbox-common:bookworm-slim がビルドされます。使用するには：

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

サンドボックスブラウザイメージ

サンドボックス内でブラウザツールを実行するには、ブラウザイメージをビルドしてください：

scripts/sandbox-browser-setup.sh

Dockerfile.sandbox-browser を使って openclaw-sandbox-browser:bookworm-slim をビルドします。コンテナは CDP 有効の Chromium とオプションの noVNC オブザーバー（Xvfb によるヘッドフル）を実行します。

注意事項：

ヘッドフル（Xvfb）はヘッドレスよりもボット検出を軽減します。
agents.defaults.sandbox.browser.headless=true を設定すればヘッドレスも使用可能。
フルデスクトップ環境（GNOME）は不要。Xvfb がディスプレイを提供。
ブラウザコンテナはグローバルな bridge の代わりに専用 Docker ネットワーク（openclaw-sandbox-browser）をデフォルトで使用。
任意の agents.defaults.sandbox.browser.cdpSourceRange で CIDR によるコンテナエッジ CDP イングレスの制限が可能（例：172.21.0.1/32）。
noVNC オブザーバーアクセスはデフォルトでパスワード保護。OpenClaw は短命のオブザーバートークン URL を提供し、ローカルブートストラップページを配信、パスワードを URL フラグメントに保持（URL クエリではなく）。
ブラウザコンテナの起動デフォルトは共有/コンテナワークロード向けに保守的であり、以下を含みます：
- --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-software-rasterizer
- --disable-gpu
- --disable-dev-shm-usage
- --disable-background-networking
- --disable-features=TranslateUI
- --disable-breakpad
- --disable-crash-reporter
- --metrics-recording-only
- --renderer-process-limit=2
- --no-zygote
- --disable-extensions
- agents.defaults.sandbox.browser.noSandbox が設定されている場合、--no-sandbox と --disable-setuid-sandbox も追加。
- 上記 3 つのグラフィックスハードニングフラグは任意。WebGL/3D が必要な場合は OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 を設定。
- エクステンション動作は --disable-extensions で制御。OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 でエクステンション依存ページ向けに無効化（エクステンション有効化）可能。
- --renderer-process-limit=2 は OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT でも設定可能。0 で Chromium のデフォルトプロセス制限を使用。

デフォルトはバンドルイメージにデフォルトで適用されます。異なる Chromium フラグが必要な場合は、カスタムブラウザイメージと独自のエントリポイントを使用してください。

使用設定：

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

カスタムブラウザイメージ：

{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-openclaw-browser" } },
    },
  },
}

有効にすると、エージェントは以下を受け取ります：

サンドボックスブラウザコントロール URL（browser ツール用）
noVNC URL（有効かつ headless=false の場合）

ツールの許可リストを使用する場合は、browser を追加し（deny から削除）しないとツールはブロックされたままです。プルーニングルール（agents.defaults.sandbox.prune）はブラウザコンテナにも適用されます。

カスタムサンドボックスイメージ

独自のイメージをビルドして設定で指定：

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-openclaw-sbx" } },
    },
  },
}

ツールポリシー（許可/拒否）

deny は allow に優先。
allow が空の場合：deny 以外のすべてのツールが利用可能。
allow が非空の場合：allow にあるツールのみ利用可能（deny を除く）。

プルーニング戦略

2 つのノブ：

prune.idleHours：X 時間使用されていないコンテナを削除（0 = 無効）
prune.maxAgeDays：X 日より古いコンテナを削除（0 = 無効）

例：

アクティブなセッションは保持しつつライフタイムを制限： idleHours: 24、maxAgeDays: 7
プルーニングしない： idleHours: 0、maxAgeDays: 0

セキュリティに関する注意事項

ハードウォールはツール（exec/read/write/edit/apply_patch）にのみ適用。
ホスト専用ツール（browser/camera/canvas）はデフォルトでブロック。
サンドボックスで browser を許可すると分離が破られます（ブラウザはホスト上で実行）。

トラブルシューティング

イメージが見つからない：scripts/sandbox-setup.sh でビルドするか、agents.defaults.sandbox.docker.image を設定。
コンテナが実行されていない：セッションごとにオンデマンドで自動作成されます。
サンドボックス内のパーミッションエラー：docker.user をマウントされたワークスペースの所有権と一致する UID:GID に設定してください（またはワークスペースフォルダの chown）。
カスタムツールが見つからない：OpenClaw は sh -lc（ログインシェル）でコマンドを実行し、/etc/profile をソースして PATH をリセットする場合があります。docker.env.PATH にカスタムツールパスをプリペンドするか（例：/custom/bin:/usr/local/share/npm-global/bin）、Dockerfile で /etc/profile.d/ にスクリプトを追加してください。