Docker Compose で OpenClaw を動かすチームがつまずく典型は、イメージが pull できないことではありません。Gateway のログは健全に見えるのに、ブラウザや CLI では接続拒否、WebSocket ハンドシェイク失敗、トークンエラーに見えるケースです。原因は多くの場合、リッスンアドレス（バインド）、ポート公開、CLI が Gateway のネットワーク名前空間を共有するかどうかであり、モデル API キーではありません。本稿ではオンコールで出やすい症状を六類型に分け、「起動していない」と「起動しているが到達できない」の二つのマトリクス、バインド・ファイアウォール・公開の対応表、コピーできる診断コマンド、六ステップの手順、ログ上の三つの KPIを整理します。Docker 本番運用、インストール後の doctor 切り分け、Kubernetes プローブの記事と併用してください。本番運用編はどうデプロイするか、本稿はコンテナ同士やホストが、想定どおり互いを見えているかを扱います。
制御面は Gateway の WebSocket／HTTP と CLI／コントロール UI、さらに 複数コンテナ・カスタムブリッジ・network_mode: service:... が重なります。層別の切り分けがないと、リスナーが CLI の名前空間から届くかを確認せずに .openclaw だけを回し続けがちです。
127.0.0.1 にバインドし、ホストは公開ポート経由で届く一方、同じ compose 内の別サービスは別経路を解決している。gateway:18789 を解決するが、Gateway は共有サービススタックに対してループバックだけを晒している—「一度は動いたが再起動後に壊れる」典型です。curl は時々成功するがコンテナ内プローブは失敗する。::1 やスリムイメージでの不適切な AAAA レコード。これらは本番運用で扱うボリューム、イメージダイジェスト、ヘルスチェックと同じ変更チケットで追跡します。到達性と版の正しさは別軸です。
compose リポジトリにネットワークトポロジーを一枚にまとめます。どのサービスがどのネットワークにいるか、誰がポートを公開するか、開発用ノートと CI がどうスタックをプローブするかです。カスタムネットワーク上の DNS はデフォルトブリッジと異なります。サービス名が失敗したら、OpenClaw を疑う前にコンテナ内で getent hosts や nslookup を実行してください。
必ず公式の doctor と gateway status を先に実行します（インストール後ガイドを参照）。リスナーの有無が分かる前にトークンを回さないでください。
| シグナル | 想定クラス | 最初のアクション | アンチパターン |
|---|---|---|---|
| Gateway コンテナが無い、または CrashLoop | 起動していない | docker logs、OOM、プローブによる Pod 終了 | リソース確認なしで pull だけを繰り返す |
動いているがコンテナ内 ss にリスナーが無い | 設定／バインド失敗 | OPENCLAW_GATEWAY_BIND と compose の command をドキュメントと突合 | ホストの /etc/hosts だけを編集する |
リスナーはあるが CLI の wget が失敗 | 名前空間をまたぐ経路 | network_mode: "service:openclaw-gateway" を検討 | 脅威モデルなしで盲目的に 0.0.0.0 にする |
| ホストのブラウザは失敗、コンテナは成功 | 公開／プロキシ | ports:、VPN、PAC を検証 | TLS を無作為に無効化する |
公式の gateway.bind に相当する値（loopback、lan、tailnet、auto など）に揃え、compose では誰がポートを公開するかも明示します。
| 目的 | バインド／環境変数の意図 | Compose での注意 | セキュリティ |
|---|---|---|---|
| ローカルノートのみ | ループバック優先。ホストは公開ポートで到達 | 127.0.0.1:18789:18789 | 他の compose サービスがループバック到達を引き継ぐと仮定しない |
| CLI を Gateway に強く結びつける | ネットワークスタックを共有 | network_mode: "service:openclaw-gateway" | ポート空間を共有する—二重バインドに注意 |
| LAN デバッグ | lan または同等 | 0.0.0.0 と特定 NIC を明示的に選ぶ | 上流のファイアウォールルールとセットで |
| トンネル／リバースプロキシ | Gateway はループバック、TLS はエッジ | ネットワークを分割し WebSocket のパススルーを確認 | 管理ポートをインターネットに裸晒しにしない |
# 1) ホスト：ポートは実際に公開されているか docker compose ps curl -sv --max-time 2 http://127.0.0.1:18789/ || true # 2) Gateway コンテナ内 docker compose exec openclaw-gateway sh -lc 'ss -lntp 2>/dev/null || netstat -lntp' # 3) CLI コンテナから（サービス名は環境に合わせて変更） docker compose exec openclaw-cli sh -lc 'wget -qO- --timeout=2 http://openclaw-gateway:18789/ || echo FAIL' # 4) 実効の compose を確認 docker compose config | sed -n '1,200p'
注意：コミュニティ報告では「CLI が Gateway に届かない」が、CLI を Gateway のネットワーク名前空間に置かない compose ファイルに結び付く例があります。本番にマージする前に、テストスタックでこのコマンドブロックで実証してください。
インストール手順が曖昧なら、まず 三プラットフォームの導入ガイド から読んでください。
Upgrade ヘッダーとパス書き換えを確認します。同じスタックをオーケストレーションに載せるときは、Kubernetes ヘルスチェックの記事 の HTTP プローブとも整合させられます。
ss のローカルアドレス、プロセス名、compose サービス—差分はチケット化します。docker port と iptables NAT—2026 年でも古いチェーンが刺さります。Gateway ログではハンドシェイク失敗と上流の 429／5xxを分けてタグ付けします。後者が支配的なら プロバイダフェイルオーバーの記事 に切り替えます。
HTTP プローブがループバックを向いているのにユーザー経路が別インターフェースから入ると、プローブはすべて緑だがユーザーはすべて赤に見えます。リリースを疑う前に、表 2 のバインド方針とプローブ URL を揃えてください。
Docker Desktop のスリープ、VPN の切り替え、ローカルプロキシは localhost の解決を変えます。本番に近い自動化には再現可能なリッスン方針、監査可能な compose リビジョン、安定したホスト境界が要ります。アドホックなノートは複数リージョンの出口とベアメタル分離も出にくく、常時 Gateway の期待と衝突しがちです。
到達可能なオンコール制御面が必要なチームでは、個人機よりプロ用クラウド Mac に Gateway を載せるほうが安定しやすいです。MACCOME はシンガポール、日本、韓国、香港、米国東海岸、米国西海岸に Mac mini M4／M4 Pro のベアメタルノードを提供します。ネットワーク切り分けの後は SSH と VNC をヘルプセンターと併読し、料金と地域ページを確定してください。
専用のテストホストでパイロットし、ログをアーカイブしてから共有 compose リポジトリに昇格させます。network_mode の暗黙知だけに頼らないでください。
一時的な 0.0.0.0 バインドには文書化したロールバックと露出レビューが必要です。切り分けの目的は、制御面を誰が見るべきかを名前空間設計と一致させることであり、リッスン範囲を最大化することではありません。
よくある質問
WSL2 でも同じマトリクスが使えますか？
手順の順序は同じで、localhost 転送の挙動が異なります。WSL2 切り分けの記事 を重ねてください。
リージョンやレンタル条件はどこで読みますか？
Gateway をクラウド Mac に載せるなら、マルチリージョンガイド と レンタル料金 を SSH 出口を固定する前に揃えてください。接続の詳細は ヘルプセンター を参照してください。