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 Kill される可能性があります）
• イメージとログに十分なディスク容量
• 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 画面にチェックアウト済みのコミットと 1 つのビルドタイムスタンプが表示されるよう、上記のとおりソースの識別情報をビルド引数として渡してください。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 専用の Skills 依存関係インストーラーを非表示にします。これらの依存関係はカスタムイメージで提供するか、手動でインストールしてください。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 のソースをテストするには、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 を有効にしてから、次の URL をスクレイプします。

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

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

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

コンテナ内では、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 にシェルで source できない値が含まれている場合は、依存している値（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 イメージでは /home/node/.local/bin が PATH に含まれているため、バンドル済みの Anthropic Plugin はアダプター設定を上書きせずにこれを解決できます。

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

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: 動作設定
• agents/<agentId>/agent/auth-profiles.json: 保存されたプロバイダーの OAuth／API キー認証
• .env: OPENCLAW_GATEWAY_TOKEN など、環境変数を基盤とするランタイムシークレット

認証プロファイルのシークレットディレクトリには、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 設定