谁会遇到问题：用 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 验证 作为后续能力扩展阅读。