2026 OpenClaw Docker Compose 本番ガイド：
ゲートウェイと実行系の分離、ヘルスチェック、起動順序の切り分け

01. 三つの失敗クラス：巨大 compose、偽ヘルス、起動競合

1) 巨大 compose の反パターン： ゲートウェイ待受、ツール実行、観測用サイドカーが一つのサービス定義に同居すると、ログが混線し、CPU スパイクがまず WebSocket を飢餓させ、インシデント対応が「全部再起動」に収束します。ロールバックも一括であり、どのサブシステムが悪さをしたのかを事後検証で切り分けにくくなります。

2) 常に成功するヘルスチェック： スタブコマンドで常にゼロを返す、あるいは誤ったポートをプローブすると、オーケストレータはスタックが健全だと判断したままチャネル初期化が未完の時間帯を生みます。その間に depends_on に従って実行系が起動し、上流への再試行を連打してディスクをノイズで埋めます。この「偽の準備完了」は VPS 上のゲートウェイ層の記事 で述べた課題の Compose 版だと捉えてください。

3) 契約ではなく慣習による順序付け： 既定の depends_on はコンテナの起動を待ちますが、アプリケーションの準備完了までは保証しません。早すぎる接続をするワーカーは、バックオフが効く前に共有ボリュームに不整合状態を書き込むことがあります。夜間メンテナンスでコンテナが再作成されると、その競合が最も困るタイミングで表面化します。

2026 年の自己ホスト OpenClaw の文脈では、Docker はすでに依存関係の衛生を買っています。次に買うべきは 観測可能な境界 と ロールバック単位 です。これらが無いままでは、Compose は YAML を纏ったシェルスクリプトに過ぎません。

02. 意思決定マトリクス：オールインワン対ゲートウェイ＋実行系対ホスト TLS エッジ

下表は、ファイル名を毎日変えるのではなく、一日から二日でトポロジを凍結するための材料です。TLS 素材とランタイムトークンを監査しやすく分離したい場合は、外部リバースプロキシを採りつつ、ゲートウェイとワーカーは Compose 内に置く構成が現実的です。

趣味スタックはオールインワンから始めても構いませんが、移行トリガー を文書化します。CPU が七十パーセントを持続する、ゲートウェイ再起動が実行系まで巻き込む、統合ログでディスク圧迫が繰り返す、といった条件です。本番志向のチームは最初からゲートウェイと実行系を分け、Docker 本番運用の五段階 のチェックリストを継承するのが無難です。

03. 前提条件：名前付きボリューム、ネットワーク、シークレット、cgroup 上限

services: を書き始める前に、四つの決定を凍結します。第一に状態を 名前付きボリューム に置くか bind mount に置くかです。開発ノートは bind が速い一方、本番は誤削除リスクを避けるため名前付きを既定にします。第二に、デフォルトブリッジで足りるか、将来のマルチホスト用オーバーレイが要るかです。本稿は単一ノードに留まりますが、判断点として挙げます。第三に openclaw.json とプロバイダ秘密の供給経路です。読み取り専用マウントと _FILE 間接、あるいは Docker secrets が、イメージ焼き込みより安全です。第四に、実行系の OOM がホスト全体を巻き込まないための メモリ上限 です。

裸の systemd と比べ、Compose の利点は同じ宣言をステージングと CI で diff できることです。イメージタグはパッチレベルまで固定し、latest 漂流による再現不能な深夜 pull を避けます。アップグレード手順書にはダイジェスト、compose ファイルのハッシュ、openclaw doctor の出力を残し、ロールバックを感情ではなく証拠に基づいて行います。

無関係な複数スタックが同一ホストを共有する場合はサービスごとに cpus とメモリ上限を宣言し、変更窓の間に docker events の oom_kill を監視します。レプリカを増やす計画があるなら、OpenClaw のチャネルが単一ライター前提かどうかを先に記録します。セッション粘着性のないまま compose scale すると、重複配送やロック競合が増幅されます。

# プロジェクト占有の確認（抜粋）
docker compose ps -a
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

04. 五段階ランブック：分離、compose、ヘルスチェック、順序、観測

1. 面を分ける： ゲートウェイは外向きプロトコルとルーティングを、実行系は CPU 負荷の高いツール呼び出しを担当します。環境テンプレートの内部ホスト名（例：gateway:18789）を再起動を跨いで安定させます。
2. プロファイル付き compose： profiles: ["full"] でデバッグ用サイドカーを本番既定から切り離し、エッジ経路の攻撃面を縮めます。
3. 正直なヘルスチェック： 実リスナーか軽量 CLI をプローブし、計測したコールドスタートより長い start_period を設定します。start_period の過小評価は、健全と不健全のフラップの主因です。
4. 条件で順序を拘束： ワーカーがチェック通過後にだけ起動するよう depends_on.condition: service_healthy を優先します。古い compose プラグインでは同等の境界再試行が必要な場合もあり、README に回避策を記録します。
5. 観測と台帳： docker compose logs -f --tail=200 の例、イメージダイジェスト、doctor 出力をチームのランブックに残します。インシデントでは YAML を変える前に切り分け表を辿ります。

Compose 断片の例（論理構成。ポートは自環境に合わせて調整）

services:
  openclaw-gateway:
    image: your/openclaw:1.2.3
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:18789/health || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 60s
  openclaw-worker:
    image: your/openclaw:1.2.3
    depends_on:
      openclaw-gateway:
        condition: service_healthy

HTTP のヘルスルートが無い場合でも、プロセスとポートの組み合わせ検査は許容されますが、ゾンビ親にマッチする単純な grep は避けます。導入ガイド と doctor のプローブを突き合わせ、実際に有効化したチャネルに整合させてください。

運用成熟度には compose 仕様の版管理も含まれます。内部モジュールにタグを付け、ネットワークに触れるマージごとに変更ログを残し、既知良好な compose ダイジェストへ戻すリハーサルを実施します。リハーサルを省くチームは、ボリューム移行が一方通行であることにアップグレード直後に気づきがちです。

05. 症状／想定原因／アクションの切り分け表

症状が TLS と公開入口に集中するなら、アプリの不具合を追う前に リバースプロキシと doctor の記事 に戻るのが早道です。短時間の検証や日割り運用では 日割り Mac デプロイの落とし穴 も参照し、権限・帯域・ツールチェーンの差分を先に潰してください。

06. 引用可能な指標とよくある誤解

• 指標 1： 2025 年から 2026 年の自己ホスト問い合わせのうち、「再起動で全部壊れた」系インシデントのおよそ 三四パーセントから四八パーセント は、最終的にコアクラッシュではなく ヘルスチェックと depends_on の意味不一致 に分類されました。
• 指標 2： ゲートウェイと実行系を分離し cgroup 上限を付けた後、同一ハードウェア条件での単一サービス制御と比較して、OOM に起因するホスト全体の利用不能はおよそ 二七パーセントから三九パーセント 減少したというフィールド報告があります。
• 指標 3： ログローテーション無しでは、混雑日の OpenClaw ノードが json-file でおよそ 1.8 から 6.2 GB を一日に出すことがあり、四十 GB 級のクラウドディスクを静かに枯らします。

誤解 A： restart: always がヘルスチェックの代替になる、という考えは誤りです。再起動嵐を増幅するだけです。誤解 B： プライベートリポジトリなら compose に本番トークンを直書きしてよい、という判断は避け、シークレットマネージャかホスト環境へ寄せます。誤解 C： ワーカー側に外向きリスナーを二重化すると、Compose のラベルでは修復不能なスプリットブレインが起きます。

会話型エージェントの信頼性には、外向きツール呼び出しの明示的レート制限と、プロバイダ制限時のバックオフも必要です。Compose 自体がそれらの方針を生み出すわけではありませんが、健全なゲートウェイ信号、有界キュー、ログ保持により強制の可否が観測可能になります。

キャパシティ計画にはコールドスタート演習を含めます。全サービスを停止し、方針が許すならエフェメラルキャッシュを消してから、ゲートウェイが健全と報告し最初のワーカーが合成チャネル ping を完了するまでの実時間を三回測定し p50 と p95 を記録します。それが start_period の根拠となり、ライブマイグレーションでハイパーバイザが停滞したときの当番期待値にもなります。ステージングでは短時間 DNS を遮断するパーティション試験を行い、ワーカーがタイトループを抜けるか文書化します。

ドキュメント負債は隠れた税金です。各 compose サービスについて README に一段落のオーナー注記を置き、ポート、ボリューム、ヘルス意味、ロールバック制約を書きます。オンボーディングが午前中を超えるチームは、多くの場合才能不足ではなくその注記不足です。注記をダッシュボードとアラート経路にリンクし、ページング担当が空の compose に着地しないようにします。

四半期ごとの「compose diff レビュー」をカレンダーに載せます。インシデントが無くても依存更新とカーネル更新はタイミング特性を変えます。ヘルス閾値、再起動方針、公開ポートを三十分見直すだけで、次のメジャーアップグレード周期まで潜むドリフトを防げます。

07. Linux Compose の常時稼働とネイティブ macOS リハーサル容量

Linux 上の Compose で OpenClaw を動かすことは、常時オン型のチームサービス と予測可能な支出には非常に合います。一方で Apple ツールチェーン同席での同一マシン検証、GUI 比重の高いチャネル調査、コンテナに日々いない同僚向けの一時間オンボーディングには弱い面があります。イメージ漂流、ボリューム権限の角、macOS 限定パスの欠落が、実際はネットワーク以外の問題を引き延ばします。

現実的な型は、本番トラフィックを Linux Compose に置き、メジャーアップグレードは 短命のネイティブ macOS でリハーサルすることです。compose トポロジを Docker Desktop かリモート Mac に縮小し、doctor とログを取得したら本番ボリュームを冒さず破棄します。接続品質と SKU 選定は リモート接続とプラン を、現金支出の比較は ベアメタル料金 と突き合わせ、レンタル窓を資本予算ではなくリハーサルカレンダーに揃えます。

安価な VPS に永住しても、過剰割当隣人、ログスパイク時のバースト I/O、評判の悪い共有 IP はフィールド報告に残ります。macOS レンタルは Linux 本番を置き換えるものではなく、アップグレードの リスク低減 と Apple 隣接ワークフローの信じられる検証室を与えます。そのためインフラ as code は Linux に置き、顧客向けチャネルに触れる前に時間制限付きネイティブ Mac で検証する、という二段構えが多くのチームに合います。

compose 特有の堅牢化は変更管理にも属します。docker-compose.yml を編集する pull request はネットワーク方針変更と同列に扱い、ポートや公開インタフェース、ボリュームマウントが動く差分には二名レビューを要求します。CI では docker compose config で YAML を検証し、まずゲートウェイ単体のスモークプロファイルで起動とヘルスを確認してからワーカーを重ね、本番の依存グラフを模倣します。マージ前に CPU と RSS をサンプリングし退行を早期に見つけます。

外部シークレットストアと統合するときは、compose の横にローテーション手順を置き、同時ロールが要る変数、ゲートウェイのみでカナリアできる変数、ワーカーが古い資格情報をどれだけ許容してから潔く終了すべきかを明文化します。部分ローテーションが認証嵐の引き金になる、というのはインシデント振り返りの定番です。最後に、アプリログとコンテナログドライバの保持方針を揃えます。Compose 側のディスクだけ最適化しても、別デーモンがパーティションを埋める矛盾を避けます。