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 により exit 137 で強制終了される場合があります）
• イメージとログ用の十分なディスク容量
• VPS/公開ホストで実行する場合は、特に Docker DOCKER-USER ファイアウォールポリシーについて、 ネットワーク公開のセキュリティ強化を確認してください。

コンテナ化された Gateway

./scripts/docker/setup.sh

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

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

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

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

環境変数

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

公式 Docker イメージには Homebrew は含まれていません。オンボーディング中、OpenClaw は brew のない Linux コンテナで実行されている場合、brew 専用の skill 依存関係インストーラーを非表示にします。これらの依存関係は、カスタムイメージで提供するか、手動でインストールする必要があります。Debian パッケージから利用できる依存関係については、イメージビルド中に OPENCLAW_IMAGE_APT_PACKAGES を使用してください。従来の OPENCLAW_DOCKER_APT_PACKAGES 名も引き続き受け付けられます。 Python 依存関係には OPENCLAW_IMAGE_PIP_PACKAGES を使用してください。これはイメージビルド中に python3 -m pip install --break-system-packages を実行するため、パッケージバージョンを固定し、信頼できるパッケージインデックスのみを使用してください。 ソースビルドでは OPENCLAW_DOCKER_BUILD_NODE_OPTIONS のデフォルトは --max-old-space-size=8192 で、tsdown ラッパーがコンテナメモリ制限を尊重できるように OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB は未設定のままにします。また、ランタイムイメージはビルド後に宣言ファイルを削除するため、 OPENCLAW_DOCKER_BUILD_SKIP_DTS=1 もデフォルトになります。Docker が ResourceExhausted、cannot allocate memory を報告する場合、または tsdown 中に中断する場合は、Docker ビルダーのメモリ制限を増やすか、 たとえば OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096 のように、より小さい明示的なヒープで再試行してください。

メンテナーは、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 ソースを含めることができます。エクスポートを有効にするには、設定で diagnostics-otel Plugin を許可して有効化し、その後 diagnostics.otel.enabled=true を設定するか、OpenTelemetry エクスポートの設定例を使用してください。コレクター認証ヘッダーは Docker 環境変数ではなく、 diagnostics.otel.headers で設定します。

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

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

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

ヘルスチェック

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

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 と loopback

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 のホスト Gateway にマッピングします。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.

Docker の Claude CLI バックエンド

公式 OpenClaw Docker イメージには Claude Code はプリインストールされていません。 OpenClaw を実行するコンテナユーザー内で Claude Code をインストールしてログインし、 イメージのアップグレードでバイナリや Claude 認証状態が消えないように、そのコンテナホームを永続化してください。

新規 Docker インストールでは、セットアップを実行する前に永続的な /home/node ボリュームを有効にします。

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

既存の Docker インストールでは、まずスタックを停止し、セットアップを再実行する前に現在の Docker .env 値を再読み込みします。セットアップスクリプトは .env を単独では読みません。 現在のシェルとデフォルトから .env を書き換えます。生成済みの .env では、次を実行します。

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

.env にシェルで source できない値が含まれている場合は、まず依存している既存の値を手動で再 export してください。 たとえば OPENCLAW_IMAGE、ポート、バインドモード、カスタムパス、OPENCLAW_EXTRA_MOUNTS、 サンドボックス、オンボーディングスキップ設定などです。生成されるオーバーレイは、openclaw-gateway と openclaw-cli の両方にホームボリュームをマウントします。

残りのコマンドは、生成された Compose オーバーレイを使って実行し、両方のサービスが永続化されたホームを マウントするようにします。セットアップで docker-compose.override.yml も使用している場合は、 docker-compose.extra.yml より前に含めてください。

その永続化されたホームに Claude Code をインストールします。

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

ネイティブインストーラーは claude バイナリを /home/node/.local/bin/claude に書き込みます。OpenClaw にそのコンテナパスを使うよう設定します。

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

同じ永続化されたコンテナホーム内からログインして確認します。

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

その後、バンドルされた claude-cli バックエンドを使用できます。

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "Say hello from Docker Claude CLI"

OPENCLAW_HOME_VOLUME は、ネイティブ Claude Code のインストールを /home/node/.local/bin と /home/node/.local/share/claude の下に永続化し、さらに Claude Code の 設定と認証状態を /home/node/.claude と /home/node/.claude.json の下に永続化します。 Claude CLI の再利用には、/home/node/.openclaw だけを永続化しても不十分です。 ホームボリュームの代わりに OPENCLAW_EXTRA_MOUNTS を使用する場合は、これらすべての Claude パスを両方の Docker サービスにマウントしてください。

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 が空のソースを持つ ボリューム仕様を出力しないようにしています。

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

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

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

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

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

ディスク増加のホットスポット: media/、セッション JSONL ファイル、共有 SQLite 状態データベース、インストール済み 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 で実行しますか?

バイナリの焼き込み、永続化、更新を含む共有 VM デプロイ手順については、 Hetzner (Docker VPS) と Docker VM Runtime を参照してください。

エージェントサンドボックス

Docker バックエンドで agents.defaults.sandbox が有効な場合、Gateway は エージェントのツール実行 (shell、ファイルの読み取り/書き込みなど) を分離された Docker コンテナ内で実行し、Gateway 自体はホスト上に残ります。これにより、Gateway 全体を コンテナ化せずに、信頼できないエージェントセッションやマルチテナントのエージェントセッションの周囲に強固な壁を設けられます。

サンドボックスのスコープは、エージェント単位 (デフォルト)、セッション単位、または共有にできます。各スコープには /workspace にマウントされた独自のワークスペースが割り当てられます。allow/deny のツールポリシー、ネットワーク分離、リソース制限、ブラウザー コンテナも設定できます。

完全な設定、イメージ、セキュリティノート、マルチエージェントプロファイルについては、以下を参照してください:

• サンドボックス化 -- サンドボックスの完全なリファレンス
• OpenShell -- サンドボックスコンテナへの対話型 shell アクセス
• マルチエージェントのサンドボックスとツール -- エージェント単位のオーバーライド

クイック有効化

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

デフォルトのサンドボックスイメージをビルドします（ソースチェックアウトから）:

scripts/sandbox-setup.sh

ソースチェックアウトなしの npm インストールでは、インラインの docker build コマンドについて サンドボックス化 § イメージとセットアップ を参照してください。

トラブルシューティング

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

関連

• インストール概要 — すべてのインストール方法
• Podman — Docker の代替としての Podman
• ClawDock — Docker Compose のコミュニティセットアップ
• 更新 — OpenClaw を最新に保つ
• 設定 — インストール後の Gateway 設定