Docker（オプション）

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

Dockerは私に適していますか？

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

このガイドでカバーする内容:

  • コンテナ化されたGateway（Docker内の完全なOpenClaw）
  • セッションごとのエージェントサンドボックス（ホストGateway + Docker分離されたエージェントツール）

サンドボックスの詳細: Sandboxing

必要要件

  • Docker Desktop（またはDocker Engine）+ Docker Compose v2
  • イメージ + ログ用の十分なディスク容量

コンテナ化されたGateway（Docker Compose）

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

リポジトリのルートから:

./docker-setup.sh

このスクリプトは:

  • Gatewayイメージをビルド
  • オンボーディングウィザードを実行
  • オプションのプロバイダーセットアップヒントを表示
  • Docker Compose経由でGatewayを起動
  • Gatewayトークンを生成し、.envに書き込み

オプションの環境変数:

  • OPENCLAW_DOCKER_APT_PACKAGES — ビルド中に追加のaptパッケージをインストール
  • OPENCLAW_EXTRA_MOUNTS — 追加のホストバインドマウントを追加
  • OPENCLAW_HOME_VOLUME — /home/nodeを名前付きボリュームで永続化

完了後:

  • ブラウザでhttp://127.0.0.1:18789/を開きます。
  • Control UI（Settings → token）にトークンを貼り付けます。

ホスト上にconfig/workspaceを書き込みます:

  • ~/.openclaw/
  • ~/.openclaw/workspace

VPS上で実行していますか？Hetzner (Docker VPS)を参照してください。

手動フロー（compose）

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

追加マウント（オプション）

追加のホストディレクトリをコンテナにマウントしたい場合は、 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と共有する必要があります。
  • OPENCLAW_EXTRA_MOUNTSを編集する場合は、docker-setup.shを再実行して 追加のcomposeファイルを再生成してください。
  • docker-compose.extra.ymlは生成されます。手動で編集しないでください。

コンテナホーム全体の永続化（オプション）

コンテナ再作成後も/home/nodeを永続化したい場合は、 OPENCLAW_HOME_VOLUME経由で名前付きボリュームを設定します。これはDockerボリュームを作成し、 /home/nodeにマウントし、標準のconfig/workspaceバインドマウントを保持します。ここでは 名前付きボリュームを使用してください（バインドパスではない）。バインドマウントには 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

注意:

  • OPENCLAW_HOME_VOLUMEを変更する場合は、docker-setup.shを再実行して 追加の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を再実行して イメージを再ビルドしてください。

より速いリビルド（推奨）

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

FROM node:22-bookworm

# Bunのインストール（ビルドスクリプトに必要）
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# パッケージメタデータが変更されない限り依存関係をキャッシュ
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

ヘルスチェック

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

注意事項

  • GatewayバインドはコンテナでのデフォルトHTTP_BIND_DEFAULT (lan)
  • Gatewayコンテナはセッションの正式な情報源です（~/.openclaw/agents/<agentId>/sessions/）。

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

詳細: Sandboxing

機能

agents.defaults.sandboxが有効な場合、非mainセッションはDocker内でツールを実行します。 Gatewayはホスト上に留まりますが、ツール実行は分離されます:

  • scope: デフォルトで"agent"（エージェントごとに1つのコンテナ + ワークスペース）
  • scope: "session"でセッションごとの分離
  • scopeごとのワークスペースフォルダを/workspaceにマウント
  • オプションのエージェントワークスペースアクセス（agents.defaults.sandbox.workspaceAccess）
  • allow/denyツールポリシー（denyが優先）
  • インバウンドメディアはアクティブなサンドボックスワークスペース（media/inbound/*）にコピーされるため、ツールが読み取れます（workspaceAccess: "rw"の場合、エージェントワークスペースに配置されます）

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

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

マルチエージェントルーティングを使用する場合、各エージェントはサンドボックス + ツール設定をオーバーライドできます: agents.list[].sandboxとagents.list[].tools（およびagents.list[].tools.sandbox.tools）。これにより、1つのGatewayで混合アクセスレベルを実行できます:

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

例、優先順位、トラブルシューティングについてはMulti-Agent Sandbox & Toolsを参照してください。

デフォルトの動作

  • Image: openclaw-sandbox:bookworm-slim
  • エージェントごとに1つのコンテナ
  • エージェントワークスペースアクセス: workspaceAccess: "none"（デフォルト）は~/.openclaw/sandboxesを使用
    • "ro"はサンドボックスワークスペースを/workspaceに保持し、エージェントワークスペースを読み取り専用で/agentにマウントします（write/edit/apply_patchを無効化）
    • "rw"はエージェントワークスペースを読み書き可能で/workspaceにマウントします
  • 自動プルーニング: アイドル > 24時間 または 経過時間 > 7日
  • Network: デフォルトでnone（明示的にオプトインが必要な場合のみエグレス）
  • デフォルトallow: exec、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
  • デフォルトdeny: browser、canvas、nodes、cron、discord、gateway

サンドボックスの有効化

setupCommandでパッケージをインストールする予定の場合は、注意してください:

  • デフォルトのdocker.networkは"none"（エグレスなし）。
  • readOnlyRoot: trueはパッケージインストールをブロックします。
  • userはapt-getには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がデフォルト)
        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でアイドルプルーニングを無効化
          maxAgeDays: 7  // 0で最大経過時間プルーニングを無効化
        }
      }
    }
  },
  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。

マルチエージェント: agents.list[].sandbox.{docker,browser,prune}.*経由でエージェントごとにagents.defaults.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がディスプレイを提供します。

設定を使用:

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

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

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

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

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

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

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

独自のイメージをビルドし、設定をそれに向けます:

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

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

ツールポリシー（allow/deny）

  • 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を設定してください。
  • コンテナが実行されていない: 必要に応じてセッションごとに自動作成されます。
  • サンドボックス内のパーミッションエラー: マウントされたワークスペースの所有権と一致するUID:GIDにdocker.userを設定してください（またはワークスペースフォルダのchownを実行）。
  • カスタムツールが見つからない: OpenClawはsh -lc（ログインシェル）でコマンドを実行し、/etc/profileをソースし、PATHをリセットする場合があります。カスタムツールパスを先頭に追加するためにdocker.env.PATHを設定してください（例: /custom/bin:/usr/local/share/npm-global/bin）、またはDockerfileで/etc/profile.d/の下にスクリプトを追加してください。
← ドキュメントに戻る