想定読者：Docker Compose で Gateway と CLI／エージェント関連コンテナを同時に動かしているが、ログ上 Gateway は動いているように見える一方、子セッションツールが gateway closed (1008): pairing required を出したり、RPC は healthy なのにペアリングで止まったりする場合です。本文の結論：「イメージを入れ直せば直る」単発問題ではなく、多くの場合 バインド面・トークン・信頼できるプロキシ帯域（trustedProxies）・コンテナ間 URL の組み合わせです。本稿では症状マトリクス、Compose 断片、六ステップ Runbook、KPI 三つを示します。他記事との役割分担：《公式 docker-setup.sh + GHCR》《ペアリングとトークン》《Docker ネットワーク切り分け》と並読してください。
OpenClaw の Gateway は長時間接続とルーティングを担います。CLI や「子セッション／子エージェント」系ツールが WebSocket／HTTP で Gateway と会話するとき、プロセスが生きているだけでは足りず、Gateway から見て呼び出し元のネットワーク上の身分が信頼できることと、ペアリング状態が有効であることが必要です。Docker は各サービスを独立したネットワーク名前空間に入れます。CLI コンテナ内で http://127.0.0.1:18789 と書くと、通信はそのコンテナ自身に向かい、ホストや別サービスには届きません。
http://openclaw-gateway:18789 のような Compose の DNS 名を使うべきです。172.16.0.0/12、10.0.0.0/8、カスタムネットワークの CIDR）を信頼済みとして宣言し、クライアント身元を正しく評価する必要があります。《三 OS インストール総覧》とは異なり、Compose で大事なのは「どの OS か」ではなくどのネットワークがどのコンテナから見て信頼されるかです。
再現するときはログの三本柱を並べて保存することをおすすめします。Gateway の起動行、サブエージェントのスタック、docker inspect で得た attachable ネットワークの Subnet です。多くの 1008 は、この三者を比較すると「信頼帯域が宣言されていない」に収まり、モデルやチャネル自体の問題ではありません。
| 症状スナップショット | 優先して確認（昇順） | よくある根本原因 |
|---|---|---|
| コンテナ A が 127.0.0.1:18789 に届かない | まずサービス名 URL に変え、publish ポートとリッスンアドレスを確認 | localhost の意味取り違い |
| RPC は healthy だが sessions_spawn が 1008 | ペアリング一覧 → trustedProxies → bind の三元組 | サブエージェント経路が外部・未ペアとみなされる |
| ログに trusted proxy／pairing の語がある | compose のネットワーク CIDR と gateway.auth 設定を揃える | 帯域が信頼集合に未登録 |
| バージョン横断アップグレード直後だけ | 新旧のデフォルト bind／auth と、移行した .openclaw ボリュームを比較 | デフォルト強化またはペアリング失効 |
ヒント： 公式の docker-setup.sh を使う場合でも、サービス名とボリュームは本文のネットワーク契約の視点で再確認してください。詳しくは《GHCR と Control UI Runbook》を参照します。
| gateway.bind（概念） | 向いている用途 | Compose との摩擦 |
|---|---|---|
| loopback | 単一コンテナの all-in-one、またはホストからだけアクセス | 他サービスコンテナはローカルループバックとして直接使えない |
| lan／カスタム Listen | マルチサービス、コンテナ間 RPC が要る | トークン／認証と露出の絞り込みが必須 |
| trusted reverse proxy | 手前に Nginx／Caddy がある | 《リバプロチェックリスト》と下流の出どころを一致させる必要がある |
trustedProxies の書き方の考え方（例となる CIDR）下表は学習用の例です。必ず docker network inspect で実 subnet を取得し、丸写しはしないでください。
| ネットワーク種別 | よくある CIDR の例 | あなたがすること |
|---|---|---|
| Docker 既定 bridge | 172.17.0.0/16（環境依存） | Gateway が見る送信元 IP がその帯域に入るか照合する |
| Compose カスタムネットワーク | 例 172.18.0.0/16～172.30.x.x | サブネット全体を trustedProxies に（単一コンテナ IP ではなく） |
| overlay／swarm | オーケストレータが割り当て | 同じく「サブネット」単位とし、Pod IP 一覧は避けてブレを減らす |
OPENCLAW_GATEWAY_URL=http://openclaw-gateway:18789（名称は compose のサービス名に合わせる）。OPENCLAW_GATEWAY_TOKEN を両側で一致させる。ファイルトークンならマウントが UID から読めることを確認します。openclaw gateway status → openclaw doctor → サブエージェント操作を再現し、ログから 1008／pairing を拾います。# 断片の例（サービス名と環境はプレースホルダー — 本番前に置き換える）
services:
openclaw-gateway:
environment:
- OPENCLAW_CONFIG_DIR=/config
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
volumes:
- ./config:/config
networks: [oc-net]
openclaw-cli:
environment:
- OPENCLAW_CONFIG_DIR=/config
- OPENCLAW_GATEWAY_URL=http://openclaw-gateway:18789
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
volumes:
- ./config:/config
networks: [oc-net]
networks:
oc-net: { driver: bridge }
gateway.auth.token の指紋または env のハッシュを比較し、不一致ならリリースを止める。これらの KPI はエンジニアリング上の可観測性の提案であり、上流プロジェクトの SLA を意味するものではありません。
「イメージが立ち上がる」だけでは足りません。サブエージェントとセッションツールは安定した Gateway・予測可能なネットワーク身分・一貫した設定ボリュームを要します。ノート PC で単一コンテナの docker run を繰り返す試行と、専用リモート Mac 上で固定 Compose と永続ボリュームを使う本番に近い運用では、故障の出方がまったく違います。後者は無人運用やスケジュールジョブのシナリオに近いと言えます。
短命な VPS や共有デスクトップはデモには使えても、一貫したディスクとネットワークの基準線を欠きがちです。Gateway・リバプロ・自動化を同じ信頼ゾーンに載せて素早く拡張したい場合、月次／四半期の組み合わせがある複数地域の Apple Silicon クラウドの方が、一時的な Docker ホストを手作業で積み重ねるより向いていることが多いです。MACCOME は物理分離と六カ国の配置を用意しており、「常時 Gateway」と「ビルド／署名機」を層分けしやすくします。まず公開料金とヘルプセンターを開き、本文の Runbook に沿って環境変数を配線してください。
導入の順番は、まず単一の Compose プロジェクトで六ステップのループを完走し、そのうえで Gateway と他ワークロードを別リモートノードに分けるか判断するのがおすすめです。
よくある質問
コード 1008 が出たら、すぐに bind を LAN に変えるべきですか？
まず表 1 の切り分けを行います。多くの場合はサービス名 URL か trustedProxiesの問題であり、リッスン面を安易に広げる話ではありません。露出を広げるときはトークンとファイアウォール方針を同時に揃えてください。ペアリングの詳細は ペアリングとトークン対照表 を参照します。
ホストで 127.0.0.1:18789 に curl すれば、コンテナ内の探査の代わりになりますか？
ホスト視点の死活にはなりますが、コンテナから Gateway のサービス名で届くかの確認の代わりにはなりません。名前空間が異なるためです。サポートは クラウド Mac サポートとヘルプセンター を参照してください。
《Docker ネットワーク切り分け》と重複しませんか？
ネットワーク切り分けは compose の名前空間と CLI 疎通を扱います。《Docker 公式ワンクリック》はイメージパスが主眼です。本稿はサブエージェントのペアリングと trustedProxies をつなぐ位置づけです。続きとして MCP と Skills の検証 もご覧ください。