Docker

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

Docker は自分に適していますか？

• はい: 分離された使い捨ての Gateway 環境が必要な場合、またはローカルインストールなしのホストで OpenClaw を実行したい場合。
• いいえ: 自分のマシンで実行していて、最速の開発ループだけが必要な場合。代わりに通常のインストールフローを使用してください。
• サンドボックス化の注記: サンドボックス化が有効な場合、デフォルトのサンドボックスバックエンドは Docker を使用しますが、サンドボックス化はデフォルトでオフであり、Gateway 全体を Docker で実行する必要はありません。SSH と OpenShell のサンドボックスバックエンドも利用できます。サンドボックス化を参照してください。

前提条件

• Docker Desktop（または Docker Engine）+ Docker Compose v2
• イメージビルド用に少なくとも 2 GB の RAM（1 GB ホストでは pnpm install が OOM により強制終了され、終了コード 137 になる場合があります）
• イメージとログ用の十分なディスク容量
• VPS/公開ホストで実行する場合は、 ネットワーク公開のためのセキュリティ強化、 特に Docker の DOCKER-USER ファイアウォールポリシーを確認してください。

コンテナ化された Gateway

./scripts/docker/setup.sh

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

docker compose run --rm openclaw-cli dashboard --no-open

# WhatsApp (QR)docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

手動フロー

セットアップスクリプトを使わずに各手順を自分で実行したい場合は、次を実行します。

docker build -t openclaw:local -f Dockerfile .docker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js onboard --mode local --no-install-daemondocker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'docker compose up -d openclaw-gateway

環境変数

セットアップスクリプトは、次の任意の環境変数を受け付けます。

メンテナーは、1 つの plugin ソースディレクトリをパッケージ済みソースパスに重ねてマウントすることで、 パッケージ済みイメージに対して同梱 plugin ソースをテストできます。例: OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro。 そのマウントされたソースディレクトリは、同じ plugin ID の一致するコンパイル済み /app/dist/extensions/synology-chat バンドルを上書きします。

可観測性

OpenTelemetry エクスポートは Gateway コンテナから OTLP コレクターへのアウトバウンドです。 公開済み Docker ポートは必要ありません。イメージをローカルでビルドし、同梱の OpenTelemetry エクスポーターをイメージ内で利用できるようにしたい場合は、そのランタイム依存関係を含めてください。

export OPENCLAW_EXTENSIONS="diagnostics-otel"export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"export OTEL_SERVICE_NAME="openclaw-gateway"./scripts/docker/setup.sh

エクスポートを有効にする前に、パッケージ版 Docker インストールでは ClawHub から公式の @openclaw/diagnostics-otel plugin をインストールしてください。カスタムのソースビルドイメージでも、 OPENCLAW_EXTENSIONS=diagnostics-otel を使ってローカル plugin ソースを含められます。 エクスポートを有効にするには、config で diagnostics-otel plugin を許可して有効化し、 diagnostics.otel.enabled=true を設定するか、OpenTelemetry エクスポートの設定例を使用してください。コレクター認証ヘッダーは Docker 環境変数ではなく、diagnostics.otel.headers で構成します。

Prometheus メトリクスは、すでに公開されている Gateway ポートを使用します。 clawhub:@openclaw/diagnostics-prometheus をインストールし、 diagnostics-prometheus plugin を有効化してから、次をスクレイプしてください。

http://<gateway-host>:18789/api/diagnostics/prometheus

このルートは Gateway 認証で保護されています。別の公開 /metrics ポートや、認証なしの リバースプロキシパスを公開しないでください。Prometheus メトリクスを参照してください。

ヘルスチェック

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

curl -fsS http://127.0.0.1:18789/healthz   # livenesscurl -fsS http://127.0.0.1:18789/readyz     # readiness

Docker イメージには /healthz に ping する組み込みの HEALTHCHECK が含まれています。 チェックが失敗し続けると、Docker はコンテナを unhealthy としてマークし、 オーケストレーションシステムが再起動または置き換えを行えます。

認証付きの詳細ヘルススナップショット:

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

LAN とループバック

scripts/docker/setup.sh はデフォルトで OPENCLAW_GATEWAY_BIND=lan を使用するため、 Docker のポート公開でホストから http://127.0.0.1:18789 へのアクセスが機能します。

• lan（デフォルト）: ホストのブラウザーとホスト CLI から公開済み Gateway ポートに到達できます。
• loopback: コンテナネットワーク名前空間内のプロセスのみが Gateway に直接到達できます。

ホストのローカルプロバイダー

OpenClaw を Docker で実行する場合、コンテナ内の 127.0.0.1 はホストマシンではなく コンテナ自体です。ホスト上で動作する AI プロバイダーには host.docker.internal を使用してください。

同梱 Docker セットアップは、これらのホスト URL を LM Studio と Ollama のオンボーディングの デフォルトとして使用します。また docker-compose.yml は、Linux Docker Engine 向けに host.docker.internal を Docker のホストゲートウェイへマッピングします。Docker Desktop は、 macOS と Windows ですでに同じホスト名を提供しています。

ホストサービスも Docker から到達可能なアドレスで待ち受ける必要があります。

lms server start --port 1234 --bind 0.0.0.0OLLAMA_HOST=0.0.0.0:11434 ollama serve

独自の Compose ファイルまたは docker run コマンドを使用する場合は、同じホストマッピングを自分で追加してください。例: --add-host=host.docker.internal:host-gateway。

Bonjour / mDNS

Docker ブリッジネットワークは通常、Bonjour/mDNS マルチキャスト（224.0.0.251:5353）を 安定して転送しません。そのため、同梱 Compose セットアップでは OPENCLAW_DISABLE_BONJOUR=1 がデフォルトになっており、ブリッジがマルチキャストトラフィックを 落としたときに Gateway がクラッシュループしたり、アドバタイズを繰り返し再起動したりしないようにしています。

Docker ホストでは、公開済み Gateway URL、Tailscale、または広域 DNS-SD を使用してください。 OPENCLAW_DISABLE_BONJOUR=0 は、ホストネットワーキング、macvlan、または mDNS マルチキャストが 動作することがわかっている別のネットワークで実行している場合にのみ設定してください。

注意点とトラブルシューティングについては、Bonjour 検出を参照してください。

ストレージと永続化

Docker Compose は OPENCLAW_CONFIG_DIR を /home/node/.openclaw に、 OPENCLAW_WORKSPACE_DIR を /home/node/.openclaw/workspace に、 OPENCLAW_AUTH_PROFILE_SECRET_DIR を /home/node/.config/openclaw にバインドマウントするため、 これらのパスはコンテナを置き換えても残ります。いずれかの変数が未設定の場合、同梱の docker-compose.yml は ${HOME} 配下にフォールバックし、HOME 自体もない場合は /tmp に フォールバックします。これにより、最小環境で docker compose up が空の source を持つ ボリューム指定を出力することを防ぎます。

そのマウントされた設定ディレクトリには、OpenClaw が次を保存します。

• 動作設定用の openclaw.json
• 保存されたプロバイダー OAuth/API キー認証用の agents/<agentId>/agent/auth-profiles.json
• OPENCLAW_GATEWAY_TOKEN など、環境変数に基づくランタイムシークレット用の .env

auth-profile シークレットキー ディレクトリには、OAuth ベースの認証プロファイルのトークンデータに 使用するローカル暗号化キーが保存されます。これは Docker ホストの状態と一緒に保持しつつ、 OPENCLAW_CONFIG_DIR とは分けてください。

インストール済みのダウンロード可能な plugins は、パッケージ状態をマウントされた OpenClaw ホーム配下に保存するため、plugin インストール記録とパッケージルートはコンテナ 置換後も保持されます。Gateway 起動時に、同梱 Plugin の依存関係ツリーは生成されません。

VM デプロイでの永続化の詳細については、 Docker VM Runtime - 何がどこに保持されるかを参照してください。

ディスク増加のホットスポット: media/、セッション JSONL ファイル、 cron/runs/*.jsonl、インストール済み plugin パッケージルート、/tmp/openclaw/ 配下のローテーションされるファイルログを監視してください。

シェルヘルパー（任意）

日常的な Docker 管理を簡単にするには、ClawDock をインストールします。

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.shecho 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

古い scripts/shell-helpers/clawdock-helpers.sh の raw パスから ClawDock をインストールしていた場合は、上のインストールコマンドを再実行して、ローカルのヘルパーファイルが新しい場所を追跡するようにしてください。

その後、clawdock-start、clawdock-stop、clawdock-dashboard などを使用します。すべてのコマンドは clawdock-help で確認できます。 ヘルパーの完全なガイドについては、ClawDockを参照してください。

export OPENCLAW_SANDBOX=1./scripts/docker/setup.sh

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

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

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

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

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

VPS で実行する場合

binary baking、永続化、更新を含む共有 VM デプロイ手順については、 Hetzner (Docker VPS) と Docker VM Runtime を参照してください。

Agent sandbox

agents.defaults.sandbox が Docker backend で有効な場合、gateway 自体はホスト上に留まり、gateway は agent tool execution（shell、ファイルの読み取り/書き込みなど）を分離された Docker コンテナ内で実行します。これにより、gateway 全体をコンテナ化せずに、信頼できない agent sessions やマルチテナントの agent sessions の周囲に強固な壁を設けられます。

Sandbox scope は agent ごと（既定）、session ごと、または shared にできます。各 scope には /workspace にマウントされる独自の workspace が割り当てられます。また、 allow/deny tool policies、network isolation、resource limits、browser containers も設定できます。

完全な設定、イメージ、セキュリティ注記、multi-agent profiles については、次を参照してください。

• Sandboxing -- sandbox の完全なリファレンス
• OpenShell -- sandbox コンテナへの対話型 shell アクセス
• Multi-Agent Sandbox and Tools -- agent ごとの overrides

クイック有効化

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off | non-main | all        scope: "agent", // session | agent | shared      },    },  },}

既定の sandbox イメージをビルドします（source checkout から）。

scripts/sandbox-setup.sh

source checkout なしの npm インストールの場合は、inline docker build コマンドについて Sandboxing § イメージとセットアップを参照してください。

トラブルシューティング

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

関連

• Install Overview — すべてのインストール方法
• Podman — Docker の代替としての Podman
• ClawDock — Docker Compose community setup
• Updating — OpenClaw を最新に保つ
• Configuration — インストール後の gateway 設定