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
1
イメージをビルドする
リポジトリのルートから実行します。これにより、Gateway イメージがローカルで ビルド済みイメージは、最初に GitHub Container Registry に公開されます。GHCR は、リリース自動化、バージョン固定デプロイ、来歴チェックの主要レジストリです。同じリリースの Docker Hub ミラーも
openclaw:local としてビルドされます。代わりにビルド済みイメージを使用するには、次のようにします。openclaw/openclaw に公開されます。ghcr.io/openclaw/openclaw または openclaw/openclaw を使用し、OpenClaw とリリース時期や保持ポリシーが異なる非公式ミラーは避けてください。バージョン固有のタグには、2026.2.26 のようなリリースや、2026.2.26-beta.1 のようなプレリリースがあります。安定版リリースでは latest と main が更新され、月末の Gateway リリースでは extended-stable のみが更新されます。バリアントには、slim、main-slim、extended-stable-slim、latest-browser、main-browser、extended-stable-browser があります。デフォルトイメージには、codex および diagnostics-otel Plugin が同梱されています。-browser バリアントには Chromium も組み込まれており、初回実行時に Playwright をインストールせずにサンドボックス化されたブラウザツールを使用する場合に便利です。2
エアギャップ環境で再実行する
オフラインホストでは、まずイメージを転送してロードします。
--offline は、OPENCLAW_IMAGE がすでにローカルに存在することを検証し、暗黙的な Compose のプルとビルドを無効にしてから、通常のフロー(.env の同期、権限修正、オンボーディング、Gateway 設定の同期、Compose の起動)を実行します。OPENCLAW_SANDBOX=1 の場合、オフラインセットアップでは、OPENCLAW_DOCKER_SOCKET の背後にあるデーモン上で、設定済みのデフォルトおよびエージェントごとのサンドボックスイメージも確認します。これには、Docker ベースのブラウザイメージに付与されたブラウザコントラクトラベルも含まれます。必要なイメージが欠落しているか古い場合、セットアップは壊れた状態を成功として報告せず、サンドボックス設定を変更せずに終了します。3
オンボーディングを完了する
セットアップスクリプトはオンボーディングを自動的に実行します。
- プロバイダーの API キーの入力を求めます
- Gateway トークンを生成し、
.envに書き込みます - 認証プロファイルの秘密鍵ディレクトリを作成します
- Docker Compose 経由で Gateway を起動します
openclaw-cli が Gateway のネットワーク名前空間を共有し、Gateway コンテナが存在した後でのみ機能するため、openclaw-gateway を直接(--no-deps --entrypoint node とともに)介して実行されます。4
Control UI を開く
http://127.0.0.1:18789/ を開き、.env に書き込まれたトークンを Settings に貼り付けます。コンテナをパスワード認証に切り替えた場合は、代わりにそのパスワードを使用します。URL をもう一度確認する必要がありますか?手動フロー
.git が除外されます。イメージの About 画面にチェックアウト済みのコミットと 1 つのビルドタイムスタンプが表示されるよう、上記のとおりソースの識別情報をビルド引数として渡してください。scripts/docker/setup.sh は、両方の値を自動的に解決して渡します。
docker compose はリポジトリのルートから実行してください。OPENCLAW_EXTRA_MOUNTS または OPENCLAW_HOME_VOLUME を有効にした場合、セットアップスクリプトは docker-compose.extra.yml を書き込みます。自身で管理している docker-compose.override.yml の後にこれを含めてください(例:-f docker-compose.yml -f docker-compose.override.yml -f docker-compose.extra.yml)。コンテナイメージのアップグレード
同じマウント済みの状態/設定を維持したまま OpenClaw イメージを置き換えると、新しい Gateway は準備完了になる前に、起動時に安全なアップグレード移行と Plugin の収束を実行します。通常のイメージアップグレードでは、別途openclaw doctor --fix を実行する必要はありません。
起動時にこれらの修復を安全に完了できない場合、Gateway は正常と報告せずに終了します。再起動ポリシーが設定されている場合、Docker、Podman、または Kubernetes では Gateway コンテナが再起動を繰り返しているように表示されることがあります。マウント済みの状態ボリュームを維持したまま、Gateway が使用するものと同じ状態/設定マウントを使用し、同じイメージをコンテナコマンドとして openclaw doctor --fix を指定して一度実行します。
環境変数
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 ビルダーのメモリ上限を増やすか、明示的にヒープを小さくして再試行してください。
選択した 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 が含まれないようにします。
--platform linux/arm64 --load または --platform linux/amd64 --load を使用します。
マルチプラットフォーム出力と、付随する SBOM/プロベナンスには、
アテステーションを保持するレジストリまたは別の Buildx 出力が必要です。プッシュ後、
マニフェストを確認し、可変のソース SHA タグではなく、
不変のダイジェストをデプロイします。
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 ポートを公開する必要はありません。ローカルでビルドしたイメージにバンドル済みエクスポーターを含めるには、次のようにします。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 をスクレイプします。
/metrics ポートや、認証されていないリバースプロキシパスを公開しないでください。Prometheus メトリクスを参照してください。
ヘルスチェック
コンテナのプローブエンドポイント(認証不要):HEALTHCHECK は /healthz に ping を送信します。失敗が繰り返されると、コンテナは unhealthy とマークされ、オーケストレーターが再起動または置換できるようになります。
認証済みの詳細なヘルススナップショット:
LAN と loopback
scripts/docker/setup.sh のデフォルトは OPENCLAW_GATEWAY_BIND=lan であるため、Docker のポート公開を使用してホスト上の http://127.0.0.1:18789 が動作します。
lan(デフォルト): ホストのブラウザーとホストの CLI は、公開された Gateway ポートにアクセスできます。loopback: コンテナのネットワーク名前空間内のプロセスだけが、Gateway に直接アクセスできます。
gateway.bind では、0.0.0.0 や 127.0.0.1 のようなホストエイリアスではなく、バインドモード値(lan / loopback / custom / tailnet / auto)を使用してください。ホストのローカルプロバイダー
コンテナ内では、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 からアクセス可能なアドレスで待ち受ける必要があります。
docker run を使用していますか?同じマッピングを自分で追加してください(例: --add-host=host.docker.internal:host-gateway)。
Docker 内の Claude CLI バックエンド
公式イメージには Claude Code がプリインストールされていません。コンテナのnode ユーザーとしてインストールしてログインし、そのコンテナホームを永続化して、イメージのアップグレードでバイナリや認証状態が消去されないようにします。
新規インストールでは、セットアップを実行する前に永続的な /home/node ボリュームを有効にします。
.env の値を再読み込みします。セットアップスクリプトは常に現在のシェルとデフォルト値から .env を書き直し、ファイル自体を自動では読み込みません。
.env にシェルで source できない値が含まれている場合は、依存している値(OPENCLAW_IMAGE、ポート、バインドモード、カスタムパス、OPENCLAW_EXTRA_MOUNTS、サンドボックス、オンボーディングのスキップ)を最初に手動で再エクスポートしてください。生成されたオーバーレイは、openclaw-gateway と openclaw-cli の両方にホームボリュームをマウントします。残りのコマンドはそのオーバーレイを使用して実行してください(使用している場合は、最初に docker-compose.override.yml も指定します)。
claude を /home/node/.local/bin/claude に書き込みます。
OpenClaw イメージでは /home/node/.local/bin が PATH に含まれているため、バンドル済みの
Anthropic Plugin はアダプター設定を上書きせずにこれを解決できます。
同じ永続化されたホームからログインして確認します。
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 パスを両方のサービスにマウントしてください。
共有の本番自動化や予測可能な Anthropic の請求には、Anthropic API キーを使用する経路を推奨します。Claude CLI の再利用は、Claude Code のインストール済みバージョン、アカウントログイン、請求、更新の動作に従います。
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など、環境変数を基盤とするランタイムシークレット
OPENCLAW_CONFIG_DIR とは分けてください。
インストールされたダウンロード可能な Plugin は、マウントされた OpenClaw ホーム配下にパッケージ状態を保存するため、インストール記録とパッケージルートはコンテナを置換しても保持されます。Gateway の起動時に、バンドル済み Plugin の依存関係ツリーが再生成されることはありません。
VM 全体の永続化について詳しくは、Docker VM ランタイム - 各データの永続化場所を参照してください。
ディスク使用量が増えやすい箇所: media/、エージェントごとの SQLite データベース、従来のセッション JSONL トランスクリプト、共有 SQLite 状態データベース、インストール済み Plugin のパッケージルート、および /tmp/openclaw/ 配下のローテーションファイルログ。
シェルヘルパー(任意)
日常的なコマンドを短くするには、ClawDockをインストールします。scripts/shell-helpers/clawdock-helpers.sh パスからインストールした場合は、上記のコマンドを再実行して、ローカルヘルパーが現在の場所を参照するようにしてください。その後、clawdock-start、clawdock-stop、clawdock-dashboard などを使用できます(完全な一覧を表示するには clawdock-help を実行してください)。
Docker Gateway のエージェントサンドボックスを有効にする
Docker Gateway のエージェントサンドボックスを有効にする
docker.sock をマウントします。サンドボックスのセットアップを完了できない場合、agents.defaults.sandbox.mode を off にリセットします。OpenClaw サンドボックスが有効なターンでは、Codex コードモードは無効になります(サンドボックス化 § Docker バックエンドを参照)。ホストの Docker ソケットをエージェントサンドボックスコンテナにマウントしないでください。自動化 / CI(非対話式)
自動化 / CI(非対話式)
-T を使用して Compose の疑似 TTY 割り当てを無効にします。共有ネットワークのセキュリティに関する注意
共有ネットワークのセキュリティに関する注意
openclaw-cli は network_mode: "service:openclaw-gateway" を使用するため、CLI コマンドは 127.0.0.1 経由で Gateway にアクセスできます。これを共有の信頼境界として扱ってください。Compose 設定では、openclaw-gateway と openclaw-cli の両方で NET_RAW/NET_ADMIN を削除し、no-new-privileges を有効にします。openclaw-cli での Docker Desktop の DNS エラー
openclaw-cli での Docker Desktop の DNS エラー
一部の Docker Desktop セットアップでは、長時間稼働する
NET_RAW の削除後、共有ネットワークの openclaw-cli サイドカーからの DNS ルックアップに失敗し、openclaw plugins install のような npm ベースのコマンドで EAI_AGAIN として表示されます。通常の運用では、デフォルトの強化済み Compose ファイルを使用してください。以下のオーバーライドは、openclaw-cli コンテナだけにデフォルトのケーパビリティを復元します。デフォルトの呼び出し方法としてではなく、レジストリアクセスを必要とする単発のコマンドに使用してください。openclaw-cli コンテナをすでに作成している場合は、同じオーバーライドを使用して再作成してください。docker compose exec/docker exec では、作成済みのコンテナの Linux ケーパビリティを変更できません。権限と EACCES
権限と EACCES
イメージは 同じ不一致が、
node(uid 1000)として実行されます。/home/node/.openclaw で権限エラーが発生した場合は、ホストのバインドマウントが uid 1000 によって所有されていることを確認してください。blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) に続く plugin present but blocked として現れることがあります。これは、プロセスの uid とマウントされた Plugin ディレクトリの所有者が一致していないことを示します。デフォルトの uid 1000 で実行し、バインドマウントの所有権を修正する方法を推奨します。OpenClaw を長期的に root として実行する意図がある場合に限り、/path/to/openclaw-config/npm を root:root に chown してください。再ビルドの高速化
再ビルドの高速化
ロックファイルが変更されない限り
pnpm install が再実行されないように、依存関係レイヤーがキャッシュされる順序で Dockerfile を構成します。上級ユーザー向けコンテナオプション
上級ユーザー向けコンテナオプション
デフォルトのイメージはセキュリティを最優先し、非 root の
node として実行されます。より多機能なコンテナにするには、以下を使用します。/home/nodeを永続化:export OPENCLAW_HOME_VOLUME="openclaw_home"- システム依存関係を組み込む:
export OPENCLAW_IMAGE_APT_PACKAGES="git curl jq" - Python 依存関係を組み込む:
export OPENCLAW_IMAGE_PIP_PACKAGES="requests==2.32.5 humanize==4.14.0" - Playwright Chromium を組み込む:
export OPENCLAW_INSTALL_BROWSER=1、または公式の-browserイメージタグを使用 - または、Playwright ブラウザを永続化ボリュームにインストール:
- ブラウザのダウンロードを永続化:
OPENCLAW_HOME_VOLUMEまたはOPENCLAW_EXTRA_MOUNTSを使用します。OpenClaw は、Linux 上でイメージの Playwright 管理 Chromium を自動検出します。
OpenAI Codex OAuth(ヘッドレス Docker)
OpenAI Codex OAuth(ヘッドレス Docker)
ウィザードで OpenAI Codex OAuth を選択すると、ブラウザの URL が開きます。Docker またはヘッドレス環境では、最終的に表示された完全なリダイレクト URL をコピーし、ウィザードに貼り付けて認証を完了します。
ベースイメージのメタデータ
ベースイメージのメタデータ
ランタイムイメージは
node:24-bookworm-slim を使用し、tini を PID 1 として実行するため、長時間稼働するコンテナでゾンビプロセスが回収され、シグナルが正しく処理されます。org.opencontainers.image.base.name や org.opencontainers.image.source を含む OCI ベースイメージアノテーションを公開します。Dependabot は固定された Node ベースダイジェストを更新します。リリースビルドでは、ディストリビューションをアップグレードする別レイヤーは実行されません。OCI イメージアノテーションを参照してください。VPS で実行しますか?
バイナリの組み込み、永続化、更新を含む共有 VM へのデプロイ手順については、Hetzner(Docker VPS)およびDocker VM ランタイムを参照してください。エージェントサンドボックス
Docker バックエンドでagents.defaults.sandbox が有効な場合、Gateway 自体はホスト上に残したまま、エージェントのツール実行(シェル、ファイルの読み書きなど)を隔離された Docker コンテナ内で実行します。Gateway 全体をコンテナ化することなく、信頼できないエージェントセッションやマルチテナントのエージェントセッションを強固に分離できます。
サンドボックスのスコープは、エージェント単位(デフォルト)、セッション単位、または共有に設定できます。各スコープには、/workspace にマウントされた独自のワークスペースが割り当てられます。ツールの許可/拒否ポリシー、ネットワーク分離、リソース制限、ブラウザコンテナも設定できます。
完全な設定、イメージ、セキュリティ上の注意事項、マルチエージェントプロファイルについては、以下を参照してください。
- サンドボックス化 — サンドボックスの完全なリファレンス
- OpenShell — サンドボックスコンテナへの対話型シェルアクセス
- マルチエージェントのサンドボックスとツール — エージェントごとのオーバーライド
クイック有効化
docker build コマンドをサンドボックス化 § イメージとセットアップで参照してください。
トラブルシューティング
イメージが見つからない、またはサンドボックスコンテナが起動しない
イメージが見つからない、またはサンドボックスコンテナが起動しない
scripts/sandbox-setup.sh(ソースチェックアウト)またはサンドボックス化 § イメージとセットアップのインライン docker build コマンド(npm インストール)を使用してサンドボックスイメージをビルドするか、agents.defaults.sandbox.docker.image をカスタムイメージに設定します。コンテナは、必要に応じてセッションごとに自動作成されます。サンドボックス内の権限エラー
サンドボックス内の権限エラー
docker.user を、マウントされたワークスペースの所有権に一致する UID:GID に設定するか、ワークスペースフォルダーを chown します。サンドボックス内でカスタムツールが見つからない
サンドボックス内でカスタムツールが見つからない
OpenClaw は
sh -lc(ログインシェル)でコマンドを実行します。このシェルは /etc/profile を読み込み、PATH をリセットする場合があります。docker.env.PATH を設定してカスタムツールのパスを先頭に追加するか、Dockerfile 内の /etc/profile.d/ 配下にスクリプトを追加します。イメージビルド中に OOM で強制終了される(終了コード 137)
イメージビルド中に OOM で強制終了される(終了コード 137)
VM には少なくとも 2 GB の RAM が必要です。より大きなマシンクラスを使用して再試行してください。
Gateway のターゲットに ws://172.x.x.x が表示される、または Docker CLI でペアリングエラーが発生する
Gateway のターゲットに ws://172.x.x.x が表示される、または Docker CLI でペアリングエラーが発生する
Gateway のモードとバインドをリセットします。