2026 OpenClaw Docker Compose：接続とペアリング（1006／1008、単一トークン、Unix／共有名前空間）Runbook

読了約20分 · MACCOME

想定読者：Docker Composeで Gateway と openclaw CLI を別コンテナへ分離したとき、ログ上は Gateway が動いて見えるのに、CLI が gateway closed（WebSocket 1006/1008）／pairing required で止まる、または env とファイルのトークンの二源化が衝突するケース。結論：ゲートウェイ URL（Compose のサービス名 or Unix ソケット）と OPENCLAW_GATEWAY_TOKEN／gateway.auth を単一のソース・オブ・トゥルースに揃える。その上で必要なら共有ネットワーク名前空間などで呼び出し面だけを収束させる。役割分担：4 月のサブエージェント 1008 + trustedProxies 記事 が広い CIDR／白名单を扱うのに対し、本稿はコンテナから Gateway がどう見えるか／同じトークンを読んでいるかに集中する。Docker ネット診断／ペアリング記事／ボリューム権限 と行き来してください。

Compose 分割ですぐ出る「ネットワークのような」根本原因五つ

  1. 127.0.0.1だけを書いた：ループバックは各コンテナ自分自身のみ。サービス間は Compose の DNS（例 http://openclaw-gateway:18789）。
  2. トークンの二経路：OPENCLAW_GATEWAY_TOKEN と設定ファイルが食い違うと401／1008 の交互に見える。
  3. Unix ソケットのマウント差：gateway.sock は親ディレクトリまで完全一致で両側に必要。UID／GID はボリューム記事に従って整合。
  4. 1006 をフラッター扱い：1006は多くの場合異常クローズ（再起動・タイムアウト－中間層）。先に再起動イベントを見る。
  5. loopback と bridge の要件が混線：loopback と等価が必要なら network_mode: service:<gateway> か、サービス名 TCP でシナリオを単一アーキへ。

チェックリストの穴が開いたまままずイメージタグをいじらない―名前空間とトークン契約より先へ進めません。

クローズイベントは Gateway stderr／CLI stdout／docker events を同タイムスタンプ帯で並べると半数は「サービス再起動／過剰ヘルスチェック」だったと判明します。

兆候上から確認着地
1006 とプロセス再起動dmesg／Docker の再起動ルール／timeoutトランスポート切断≠ペアだけの話
1008＋ pairing単一ソースの Token → URL → 状態ディスク共有ボリューム欠如／二経路トークン
CLI コンテナのみ refusedCLI コンテナ内で確認（宿主 curl は補助）localhost 錯視／ポート未公開
ソケット ENOENT／権限ls -la と親ファイル全体親子ディレクトリの見えない一方通行
warning

クローズコード単体には意味が薄い：1006/1008 と Gateway の行頭ログ／状態機／反代側リトライを同時に読まないと、bind を広げる／何度も onboard だけが増えて危険面が広がります。

六ステップ実務：①到達証明のあとだけ pairing を語る

  1. トークン先の単一宣言：ファイルか env のどちらかだけを運用ソースにし、docker compose config の結果を張る。
  2. ゲートウェイ宛の話法を単一：TCP が全部サービスか、unix が同一マウントか—変更チケット内でブレさせない。
  3. .openclaw：ボリューム記事のチェックリストまで落とす。
  4. 状態と doctor：openclaw gateway status → openclaw doctor。ホストとコンテナのログ粒度をそろえる。
  5. loopback と等価が要求されるなら仕様明示：network_mode: service:<gateway> 等をレビューシートへ。trustedProxies と矛盾させない：該当記事。
  6. 変更完了の証拠：CLI名前空間の成功ログ＋ゲートウェイ URL／トークンの短いハッシュ。口頭のみはクローズしない。

Nginx/Caddy 経由なら Upgrade／timeout と Compose 側 Gateway URL が食い違わないことを先に：リバースプロキシ。

yaml
# 名前とボリュームは置換してください。適用前に docker compose config
services:
  openclaw-gateway:
    environment:
      - OPENCLAW_CONFIG_DIR=/data/.openclaw
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
    volumes:
      - oc-data:/data/.openclaw
    networks: [oc-net]

  openclaw-cli:
    environment:
      - OPENCLAW_CONFIG_DIR=/data/.openclaw
      - OPENCLAW_GATEWAY_URL=http://openclaw-gateway:18789
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
    volumes:
      - oc-data:/data/.openclaw
    networks: [oc-net]
    depends_on:
      - openclaw-gateway

networks:
  oc-net:
    driver: bridge

volumes:
  oc-data:

変更請求へ残すべき三段メモ（SLA と無関係）

  • 異常コンテナの名前空間でしか検査しないホストのみの結果はシャドウ問題を作ります。
  • 短いフィンガープリントでトークンの一致を自動ブロックしてください。
  • ヘルズプローブ暴走は 1006 を増やすだけ—まず準備チェックへ。
  • 「私のノートでも動いた」の禁止令：壊れたイメージでの再現がないログは RCA から外れる。

一時的コンテナのみでは運用チェーンになりにくい理由

OpenClaw Gateway を常駐＋自動化＋秘密ローテに載せると、マウントの隙間ですぐトークンと状態が離れます。独占できるクラウド Mac（六国・月／季のレンジ）ほうがログと再起動の監査線が読みやすい。MACCOME のレンジはまず公開 価格表で確認してください。

まとめ：契約より先にはヒューローがいない

OpenClaw の Compose 障害大半は名前空間・トークン・状態ディスクの三点がひとつの運用上の契約にまとまっていない状態です。コンテナで再現できる握手指を明示できない側の提案は後ろに回してください。整理後は GHCR と Control UI と TLS／WS の記事へ。

FAQ

trustedProxies／サブ記事とはどう読み分ける？

広い CIDR 戦略／子エージェントはそちら。本書はコンテナ側 URL とトークン収束だけを扱います。交互参照必須です。

ホスト側 curl が通れば十分？

不十分です。失敗コンテナでも同様のチェックコマンドを実行してください。