Docker（オプション）¶

Docker は任意です。 Docker は オプション です。コンテナ化されたゲートウェイを使いたい場合、または Docker フローを検証したい場合にのみ使用してください。

Docker は自分に向いていますか？¶

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

このガイドの内容：

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

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

要件¶

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

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

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

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

./docker-setup.sh

このスクリプトは次を行います：

ゲートウェイイメージをビルド
オンボーディングウィザードを実行
オプションのプロバイダ設定ヒントを印刷
Docker Compose 経由でゲートウェイを起動
ゲートウェイトークンを生成し、.env に書き込み

オプションのenv vars:

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

完了後：

ブラウザーで http://127.0.0.1:18789/ を開きます。
Control UI（Settings → token）にトークンを貼り付けます。
もう一度URLを入力しますか？ URL が再度必要ですか？docker compose run --rm openclaw-cli dashboard --no-open を実行してください。

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

~/.openclaw/
~/.openclaw/workspace

VPSで実行していますか？ 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

Note: repoルートからdocker compose ...を実行します。注記：リポジトリルートから 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>

Control 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>

詳細：Dashboard、Devices。

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

追加のホストディレクトリをコンテナにマウントしたい場合は、 docker-setup.sh を実行する前に OPENCLAW_EXTRA_MOUNTS を設定してください。これは Docker のバインドマウントのカンマ区切りリストを受け取り、openclaw-gateway と openclaw-cli の両方に適用するため、docker-compose.extra.yml を生成します。これはコンマで区切られた 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 全体を永続化（オプション）¶

/home/node をコンテナ再作成後も永続化したい場合は、 OPENCLAW_HOME_VOLUME で名前付きボリュームを設定してください。これにより Docker ボリュームが作成され、 /home/node にマウントされます。標準の設定 / ワークスペースのバインドマウントは維持されます。ここでは名前付きボリュームを使用してください（バインドパスではありません）。バインドマウントを使用する場合は、OPENCLAW_EXTRA_MOUNTS を使用してください。これにより、Docker ボリュームが作成され、 /home/node にマウントされ、標準の config/workspace バインドマウントが維持されます。 32. ここでは名前付きボリュームを使用してください（バインドパスではありません）。バインドマウントの場合は 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 を再実行してイメージを再ビルドしてください。

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

既定の 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) として実行されます。イメージは 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 の再実行を回避できます：ロックファイルが変更されない限り、 pnpm install の再実行を回避します。

FROM node:22-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 コンテナを使用してチャンネルを設定し、必要に応じてゲートウェイを再起動してください。

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 をコピーし、ウィザードに貼り付けて認証を完了してください。 Docker またはでは、コールバックにブラウザエラーが表示されるヘッドレス設定があります。完全なリダイレクト URLをコピーし、ウィザードに貼り付けて認証を完了します。

ヘルスチェック¶

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 のバインドは、コンテナ用途では既定で lan です。
Dockerfile の CMD は --allow-unconfigured を使用します。local ではなく gateway.mode を用いてマウントされた設定でも起動します。ガードを強制するには CMD を上書きしてください。ガードを強制するためにCMDを上書きします。
ゲートウェイコンテナは、セッション（~/.openclaw/agents/<agentId>/sessions/）の信頼できる情報源です。

エージェントサンドボックス（ホストゲートウェイ + Docker ツール）¶

詳細：Sandboxing

何をするか¶

agents.defaults.sandbox を有効にすると、メイン以外のセッション は Docker コンテナ内でツールを実行します。ゲートウェイはホストに残り、ツール実行のみが分離されます：ゲートウェイはホスト上にとどまりますが、ツールの実行は分離されています:

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

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

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

マルチエージェントルーティングを使用する場合、各エージェントは agents.list[].sandbox および agents.list[].tools（および agents.list[].tools.sandbox.tools）を上書きできます。これにより、1 つのゲートウェイで異なるアクセスレベルを混在させられます：これにより、1 つのゲートウェイで混合アクセスレベルを実行できます。

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

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

既定の挙動¶

イメージ：openclaw-sandbox:bookworm-slim
エージェントごとに 1 コンテナ
エージェントワークスペースアクセス：workspaceAccess: "none"（既定）は ~/.openclaw/sandboxes を使用
"ro" はサンドボックスワークスペースを /workspace に保持し、エージェントワークスペースを /agent に読み取り専用でマウント（write / edit / apply_patch を無効化）
"rw" はエージェントワークスペースを /workspace に読み書きでマウント
自動プルーン：アイドル > 24 時間または経過 > 7 日
ネットワーク：既定で none（外向き通信が必要な場合は明示的にオプトイン）
既定で許可：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"（外向き通信なし）です。
readOnlyRoot: true はパッケージインストールをブロックします。
apt-get の場合はuser をルートにする必要があります(user を省略するか、user: "0:0"を設定します)。 setupCommand (またはdocker config) がに変更されたときに、コンテナが最近使用された (約 5 分以内) でない限り、OpenClaw はコンテナを自動的に再作成します。ホットコンテナは openclawサンドボックスを再作成する...コマンドで警告をログに記録します。

{
  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。

マルチエージェント：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 の場合）

ツールに許可リストを使用している場合は、browser を追加（そして拒否から削除）するか、ツールがブロックされたままになります。 prune rules (agents.defaults.sandbox.prune) はブラウザコンテナにも適用されます。

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

独自のイメージをビルドし、設定で指定してください：

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

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

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

deny は allow より優先されます。
allow が空の場合：拒否を除くすべてのツールが利用可能です。
allow が非空の場合：allow 内のツールのみが利用可能です（拒否を除く）。

プルーン戦略¶

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をリセットすることができます。カスタムツールが見つからない：OpenClaw は sh -lc（ログインシェル）でコマンドを実行し、 /etc/profile を読み込むため PATH がリセットされる場合があります。docker.env.PATH を設定してカスタムツールのパス（例：/custom/bin:/usr/local/share/npm-global/bin）を先頭に追加するか、 Dockerfile 内で /etc/profile.d/ 配下にスクリプトを追加してください。

Install overview

Other install methods

Maintenance

Hosting and deployment

Advanced

Docker

Docker（オプション）¶

Docker は自分に向いていますか？¶

要件¶

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

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

手動フロー（compose）¶

Control UI トークン + ペアリング（Docker）¶

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

コンテナの home 全体を永続化（オプション）¶

追加の apt パッケージをインストール（オプション）¶

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

権限 + EACCES¶

高速な再ビルド（推奨）¶

チャンネルセットアップ（オプション）¶

OpenAI Codex OAuth（ヘッドレス Docker）¶

ヘルスチェック¶

E2E スモークテスト（Docker）¶

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

注記¶

エージェントサンドボックス（ホストゲートウェイ + Docker ツール）¶

何をするか¶

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

既定の挙動¶

サンドボックス化を有効化¶

既定のサンドボックスイメージをビルド¶

サンドボックス共通イメージ（オプション）¶

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

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

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

プルーン戦略¶

セキュリティ注記¶

トラブルシューティング¶

Install overview

Other install methods

Maintenance

Hosting and deployment

Advanced

Docker（オプション）¶

Docker は自分に向いていますか？¶

要件¶

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

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

手動フロー（compose）¶

Control UI トークン + ペアリング（Docker）¶

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

コンテナの home 全体を永続化（オプション）¶

追加の apt パッケージをインストール（オプション）¶

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

権限 + EACCES¶

高速な再ビルド（推奨）¶

チャンネル セットアップ（オプション）¶

OpenAI Codex OAuth（ヘッドレス Docker）¶

ヘルスチェック¶

E2E スモークテスト（Docker）¶

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

注記¶

エージェント サンドボックス（ホスト ゲートウェイ + Docker ツール）¶

何をするか¶

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

既定の挙動¶

サンドボックス化を有効化¶

既定のサンドボックス イメージをビルド¶

サンドボックス 共通イメージ（オプション）¶

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

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

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

プルーン戦略¶

セキュリティ注記¶

トラブルシューティング¶

チャンネルセットアップ（オプション）¶

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

エージェントサンドボックス（ホストゲートウェイ + Docker ツール）¶

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

既定のサンドボックスイメージをビルド¶

サンドボックス共通イメージ（オプション）¶

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

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

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