誰會遇到問題：用 Docker Compose 同時跑 Gateway 與 CLI/代理相關容器，日誌裡 Gateway 「看起來在跑」，但子會話/工具一調用就出現 gateway closed (1008)：pairing required，或 RPC 顯示健康卻仍卡在配對。本文結論：這不是「再重裝一遍鏡像」能解決的孤立問題，而往往是 綁定面、Token、可信代理網段（trustedProxies）與容器間 URL 的組合問題；本文給出症狀矩陣、Compose 片段、六步 Runbook 與三 KPI。分工：與《官方 docker-setup.sh + GHCR》《配對與 Token》《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）聲明為可信以正確識別客戶端身份。與《三平臺安裝總覽》不同：Compose 的重點不是「裝在哪個 OS」，而是哪張網在哪個容器眼裡算可信。
當你復現問題時，建議把三條日誌指紋並排保存：Gateway 啟動行、子代理調用棧、以及 docker inspect 裡 attachable 網絡的 Subnet——很多 1008 在對比這三者後會落在「未聲明可信網段」而不是模型或通道本身。
| 症狀快照 | 優先核查（升序） | 常見根因 |
|---|---|---|
| 容器 A ping 不通 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 / 自定義監聽 | 多服務、需跨容器 RPC | 必須配 token / auth 且收緊暴露面 |
| 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 兩側一致；若用文件 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 hash，不一致立即阻斷髮布。上述 KPI 為工程可觀測性建議，不構成上遊項目 SLA 承諾。
僅靠「能拉起鏡像」不夠：子代理與會話工具要求穩定 Gateway、可預測網絡身份與一致配置卷。在筆記本上反覆 docker run 單容器試玩與在獨佔遠程 Mac 上用固定 Compose 與持久卷跑長任務，故障面完全不同：後者更接近真實業務無人值守與定時任務場景。
純函數式 VPS 或共享桌面雖能短期跑通 demo，卻常常缺少一致的磁碟與網絡基線；當團隊需要把 Gateway、反代與自動化任務放在同一可信區域並快速擴容時，使用具備多地區節點、可按月租/季租組合的 Apple Silicon 雲主機，往往比反覆手搓臨時 Docker 主機更適合承載 OpenClaw 這類常駐自動化。MACCOME 提供物理隔離與六國區位選擇，便於把「網關常駐 + 構建/籤名機」分層部署；可先打開租賃價格說明與幫助文檔，再按本文 Runbook 綁定環境變量。
落地順序建議：先在單 Compose 項目裡跑滿六步閉環，再評估是否需要把 Gateway 與其他工作負載拆到不同遠程節點。
常見問題
1008 出現時要不要立刻改 bind 為 lan？
先完成表 1 的分診：很多時候是服務名 URL 或 trustedProxies問題，而不是盲目放大監聽面。擴大暴露必須同步 token 與防火牆策略。更多配對場景見 配對與 Token 對照清單。
可以在宿主機 curl 127.0.0.1:18789 代替容器內探測嗎？
可以作宿主視角探活，但不能替代容器到 Gateway 服務名的連通性驗證，兩者網絡命名空間不同。需要幫助可查看 幫助中心。
與《Docker 網絡分診》重複嗎？
網絡分診篇覆蓋 compose 命名空間與 CLI 連通；《Docker 官方一鍵》偏鏡像路徑。本文專門銜接子代理 pairing 與 trustedProxies。也可瀏覽 MCP 與 Skills 驗證 作為後續能力擴展閱讀。