Docker

Docker は任意です。分離された使い捨ての Gateway 環境や、ローカルインストールのないホストで使用してください。すでに自分のマシンで開発している場合は、代わりに通常のインストールフローを使用してください。

デフォルトのサンドボックスバックエンドは、agents.defaults.sandbox が有効な場合に Docker を使用しますが、サンドボックスはデフォルトで無効であり、Gateway 自体を Docker で実行する必要はありません。SSH および OpenShell サンドボックスバックエンドも利用できます。サンドボックスを参照してください。

複数のユーザーをホストしますか？テナントごとに 1 つのセルを使用するモデルについては、マルチテナントホスティングを参照してください。

前提条件

• Docker Desktop（または Docker Engine）+ Docker Compose v2
• イメージのビルド用に 2 GB 以上の RAM（1 GB のホストでは、pnpm install が終了コード 137 で OOM により強制終了される場合があります）
• イメージとログ用の十分なディスク容量
• 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>"

手動フロー

BUILD_GIT_COMMIT="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"docker build \  --build-arg "GIT_COMMIT=${BUILD_GIT_COMMIT}" \  --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \  -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 コンテキストでは .git が除外されます。上記のようにソースの識別情報をビルド引数として渡すことで、イメージの About 画面にチェックアウト済みのコミットと単一のビルドタイムスタンプが表示されます。scripts/docker/setup.sh は両方の値を自動的に解決して渡します。

コンテナイメージのアップグレード

マウント済みの状態／設定を維持したまま OpenClaw イメージを置き換えると、新しい Gateway は準備完了になる前に、起動時に安全なアップグレード移行と Plugin の収束処理を実行します。通常のイメージアップグレードでは、別途 openclaw doctor --fix を実行する必要はありません。

起動時にこれらの修復を安全に完了できない場合、Gateway は正常と報告せずに終了します。再起動ポリシーが設定されている場合、Docker、Podman、または Kubernetes では Gateway コンテナが再起動を繰り返しているように表示されることがあります。マウント済みの状態ボリュームを維持し、Gateway が使用するものと同じ状態／設定マウントを使って、同じイメージをコンテナコマンドとして openclaw doctor --fix を指定して一度実行します。

docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixpodman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix

doctor の完了後、デフォルトコマンドで Gateway コンテナを再起動します。Kubernetes では、同じ PVC をマウントした一回限りの Job またはデバッグ Pod で同じコマンドを実行してから、Deployment または StatefulSet を再起動します。

環境変数

scripts/docker/setup.sh（および Gateway コンテナについては docker-compose.yml から直接）で受け付ける任意の変数：

公式イメージには Homebrew は含まれていません。オンボーディング中、OpenClaw は brew のない Linux コンテナでは brew 専用のスキル依存関係インストーラーを非表示にします。これらの依存関係はカスタムイメージで提供するか、手動でインストールしてください。Debian パッケージとして提供される依存関係には OPENCLAW_IMAGE_APT_PACKAGES を、Python の依存関係には OPENCLAW_IMAGE_PIP_PACKAGES を使用してください（ビルド時に python3 -m pip install --break-system-packages を実行するため、バージョンを固定し、信頼できるインデックスのみを使用してください）。

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

選択した Plugin を含むソースビルドイメージ

OPENCLAW_EXTENSIONS は、ソースチェックアウトから Plugin マニフェスト ID を選択します。 異なる場合は、既存のソースディレクトリ名も使用できます。Docker ビルドは選択内容を一度だけソースディレクトリに解決し、本番用の 依存関係をインストールします。また、選択された Plugin が openclaw.build.bundledDist: false として個別に公開されている場合、そのランタイムをルートのバンドル済み dist にコンパイルします。この Docker 専用のパッケージングによって、Plugin の npm または ClawHub アーティファクトの契約が変わることはありません。不明、無効、または曖昧な ID はイメージビルドを失敗させます。 既知の依存関係専用またはソース専用 ID は、コンパイル済みルート dist エントリを追加せず、 既存のソースと依存関係のステージングを維持します。統合ビルドエントリを持つ選択済み Plugin は、 正常にコンパイルされる必要があります。選択されていない外部 Plugin の ソースとランタイム出力は削除されます。

たとえば、次のコマンドは ClickClack、Slack、Microsoft Teams 用に、独立したマルチアーキテクチャのスタンドアロン FakeCo Gateway イメージをビルドします。ClawRouter は すでにルートの OpenClaw ランタイムの一部であるため、ClickClack イメージでは clickclack のみを選択します。ブラウザー引数を明示的に空にすることで、デフォルトイメージに Chromium が含まれないようにします。

SOURCE_SHA="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"REGISTRY="registry.example.com/fakeco" build_gateway_image() {  gateway="$1"  selected_plugin="$2"  docker buildx build \    --platform linux/amd64,linux/arm64 \    --build-arg "GIT_COMMIT=${SOURCE_SHA}" \    --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \    --build-arg "OPENCLAW_EXTENSIONS=${selected_plugin}" \    --build-arg OPENCLAW_INSTALL_BROWSER= \    --provenance=mode=max \    --sbom=true \    --tag "${REGISTRY}/openclaw-${gateway}:${SOURCE_SHA}" \    --push \    .} build_gateway_image clickclack clickclackbuild_gateway_image slack slackbuild_gateway_image teams msteams

単一のネイティブローカルビルドには、--platform linux/arm64 --load または --platform linux/amd64 --load を 使用します。マルチプラットフォーム出力と添付された SBOM/プロベナンスには、 レジストリ、またはアテステーションを保持する別の Buildx 出力が必要です。プッシュ後は マニフェストを検査し、変更可能なソース SHA タグではなく、不変のダイジェストをデプロイします。

docker buildx imagetools inspect \  "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# デプロイ: registry.example.com/fakeco/openclaw-clickclack@sha256:<manifest-digest>

これらのイメージは、スタンドアロンの OCI ベース Gateway と一般的な Docker ユーザー向けです。 Crabhelm で管理される Gateway はこれらを使用しません。この配布経路では、 OpenClaw npm tarball を含む別の x86_64 アプライアンスアーカイブをビルドし、 Node、アーカイブ、マニフェストのダイジェストを固定します。同じマージ済み OpenClaw ソースから、 そのアプライアンスを個別にビルドしてください。

パッケージ化されたイメージに対してバンドル済み Plugin ソースをテストするには、1 つの 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 ポートを公開する必要はありません。ローカルでビルドするイメージにバンドル済みエクスポーターを含めるには、次のようにします。

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

公式のビルド済みイメージには、すでに diagnostics-otel がバンドルされています。削除した場合に限り、clawhub:@openclaw/diagnostics-otel を自分でインストールしてください。エクスポートを有効にするには、設定で 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   # ライブネスcurl -fsS http://127.0.0.1:18789/readyz     # レディネス

イメージ組み込みの HEALTHCHECK は /healthz に ping します。失敗が繰り返されると、コンテナは 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 に直接アクセスできます。

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

コンテナ内の 127.0.0.1 はホストではなく、コンテナ自体を指します。ホスト上で実行されるプロバイダーには host.docker.internal を使用してください。

バンドル済みセットアップでは、これらの URL を LM Studio/Ollama のオンボーディング時のデフォルトとして使用します。また、docker-compose.yml は Linux Docker Engine 上で host.docker.internal をホスト 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 バックエンド

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

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

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

既存のインストールでは、まずスタックを停止し、現在の .env の値を再読み込みします。セットアップスクリプトは常に現在のシェルとデフォルト値から .env を書き換え、ファイル自体を自動では読み込みません。

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

.env にシェルで読み込めない値が含まれている場合は、使用する値（OPENCLAW_IMAGE、ポート、バインドモード、カスタムパス、OPENCLAW_EXTRA_MOUNTS、サンドボックス、オンボーディングのスキップ）を先に手動で再エクスポートしてください。生成されたオーバーレイは、openclaw-gateway と openclaw-cli の両方にホームボリュームをマウントします。残りのコマンドはそのオーバーレイを使用して実行してください（docker-compose.override.yml を使用する場合は、それも先に指定します）。

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 "Docker Claude CLI からこんにちはと言ってください"

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

Bonjour / mDNS

Docker ブリッジネットワークは通常、Bonjour/mDNS マルチキャスト（224.0.0.251:5353）を確実には転送しません。OPENCLAW_DISABLE_BONJOUR が未設定の場合、バンドル済み Bonjour Plugin は、コンテナ内で実行されていることを検出すると LAN アドバタイズを自動的に無効化するため、ブリッジが破棄するマルチキャストを再試行し続けてクラッシュループすることはありません。検出結果に関係なく強制的に無効にするには OPENCLAW_DISABLE_BONJOUR=1 を、強制的に有効にするには 0 を設定します（ホストネットワーク、macvlan、または mDNS マルチキャストが動作すると確認されている別のネットワークでのみ使用してください）。

それ以外の Docker ホストでは、公開された Gateway URL、Tailscale、または広域 DNS-SD を使用してください。注意点とトラブルシューティングについては、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.json
• 保存されたプロバイダー OAuth/API キー認証用の agents/<agentId>/agent/auth-profiles.json
• OPENCLAW_GATEWAY_TOKEN など、環境変数を介するランタイムシークレット用の .env

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

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

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

ディスク使用量が増えやすい箇所: media/、エージェントごとの SQLite データベース、従来のセッション JSONL トランスクリプト、共有 SQLite 状態データベース、インストール済み Plugin のパッケージルート、/tmp/openclaw/ 配下のローテーションファイルログ。

シェルヘルパー（任意）

日常的なコマンドを短縮するには、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 パスからインストールした場合は、ローカルヘルパーが現在の場所を参照するように、上記のコマンドを再実行してください。その後、clawdock-start、clawdock-stop、clawdock-dashboard などを使用できます（完全な一覧は clawdock-help を実行してください）。

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 ランタイムを参照してください。

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

Docker バックエンドで agents.defaults.sandbox を有効にすると、Gateway 自体はホスト上に維持したまま、エージェントツールの実行（シェル、ファイルの読み書きなど）が隔離された Docker コンテナ内で行われます。Gateway 全体をコンテナ化せずに、信頼できない、またはマルチテナントのエージェントセッションを強固に隔離できます。

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

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

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

クイック有効化

{  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 設定