痛点：manifest 干净≠运行时单一真理
Compose 把依赖关系写成 YAML，但密钥仍可能出现「双重真理」：一边是 compose 提前展开的 OPENCLAW_GATEWAY_TOKEN，一边是只读挂载的 openclaw.json 里的 gateway.auth.token；两边不等价时，RPC 可能短暂成功而 WebSocket 立刻断开。
WebSocket 关闭码不是摆设：1006 多半指向链路异常（代理超时、TLS 被掐、RST），1008 常指向策略拒绝（令牌不符、Origin 不匹配）；只看 HTTP 200 的 /health 会把两类问题搅成一团。
配对流程依赖本地中间文件；匿名卷在 force-recreate 后被清空，就会出现客户端卡在「配对中」而服务端其实早就重启完毕的假象。
反向代理终止 TLS 时，空闲超时往往短于客户端 ping 间隔；生产环境才触发而本地直连永远重现不了，这是排查时要最先对齐的参数。
升级镜像后旧 JSON 仍挂载，会与 split-brain 文章描述的情形交织：要把二进制漂移与令牌漂移分开取证，否则值班会被误导去改 URL。
日志 sidecar 偷偷 chmod 了配对目录却无人知晓，会让配对间歇失败却又找不到容器崩溃证据。
同一宿主机并存 Kubernetes 与 compose 且使用 host 网络时，端口碰撞会把 WebSocket 拒绝伪装成认证失败。
备份不含 compose 项目名，在新命名空间恢复卷会把旧 pairing 碎片塞进新栈，制造幽灵会话。
与官方文档一致的分层排查
官方 troubleshooting 顺序仍是：进程→传输→鉴权→配对；compose 只是换成 docker logs / inspect 收集证据。
进程层确认监听端口未抖动重启；不要被 systemd/launchd 心智绑架而忽略容器 ENTRYPOINT 是否 fork 出错。
传输层核对端口映射、host 网络选择、防火墙与 IPv6；NAT 与直连差别巨大。
鉴权层选定单一权威令牌来源并写入值班手册；Vault→文件的渲染时间要与 compose up 顺序对齐。
配对层使用命名卷并校验 UID/GID；rootless 场景要写清楚映射参数。
治理层规定 compose merge 必须双人复核 secrets/env_file/mounts。
指标与阈值（可按业务调参）
registry 拉镜像若不稳定，start_period 建议先到四十五秒，必要时九十秒直到 SLA 明确。
外部合成探测 WebSocket 一分钟一次，内部 curl 十五秒一次；频率不对称能帮助判定 WAN 还是本地问题。
SSD 上配对耗时应在十秒内；超过四十秒观察磁盘队列或 inode。
令牌端到端轮换目标五分以内；超时就把 Vault 与 compose 放进同一编排流水线。
关闭码日志保留十四天至少；合规更高要求可三十天并做 IP 伪匿名。
CPU cgroup throttle 会拉长握手却不报错；面板需要这一项。
拓扑 × 令牌 × WebSocket × 配对
| 拓扑 | 令牌策略 | WebSocket | 配对要点 |
|---|---|---|---|
| 端口映射 bridge | 单源或明确镜像链 | 发布端口与客户端 URL 对齐 | 命名卷存 pairing |
| network_mode:host | JSON 常作主源 | 无 NAT 但要避开端口冲突 | 路径接近裸机 |
| 反向代理 TLS | 令牌只在服务端 | idle 大于 ping；保留 Upgrade | 必要时会话粘性 |
| Sidecar 注入 | 避免挂载竞态 | 勿混淆 sidecar 日志 | 严禁 GC 共享配对卷 |
矩阵衔接 bridge/host/反向代理/sidecar；更多对比见 Docker 安装路径文。
经济性：漂移 QA 往往比基准租用节点昂贵。
详见 安装路径对比。
compose 片段（示例值需替换）
version: "3.9"
services:
openclaw-gateway:
image: ghcr.io/example/openclaw-gateway:latest
env_file:
- .env.gateway
environment:
OPENCLAW_GATEWAY_TOKEN: "${OPENCLAW_GATEWAY_TOKEN}"
volumes:
- ./openclaw.json:/etc/openclaw/openclaw.json:ro
- gateway_pairing:/var/lib/openclaw/pairing
ports:
- "18789:18789"
healthcheck:
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:18789/health"]
interval: 30s
timeout: 5s
retries: 5
start_period: 45s
volumes:
gateway_pairing:
步骤 1：导出 compose config 与日志前缀。
步骤 2：选定令牌权威。
步骤 3：配对挂载命名卷。
步骤 4：拉长 start_period。
步骤 5：对齐 idle 与 Upgrade。
步骤 6：运行 doctor。
步骤 7：记录轮换窗口。
步骤 8：URL 可疑请看 远程网关矩阵。
延伸阅读与站内导航
读完本文继续对照远程网关矩阵核对 gateway.remote.url，不要把 URL 问题误判为令牌问题。
split-brain 文章帮助分辨二进制版本与 JSON 版本错位。
导航：首页、套餐、帮助页评估是否需要全天候远程 Mac。
FAQ 与收束
FAQ 连接日常 compose 约束；如涉及个人信息出境仍需法务单独评审。
混合 bare metal 与编排集群务必指定 identity owner，否则轮换撞车。
为什么 env 与 JSON 会打架？
Compose 早期展开 .env，bind-mount 稍后才到位——要明确优先级并文档化。
1008 一定是密钥错吗？
多半是策略或 Origin；读完服务端 reason。
recreate 后配对卡住？
匿名卷丢文件；换命名卷并做好备份。
合规要注意什么？
最小化 WebSocket 日志字段并按目的限定留存。
工单标注 compose project。
总结：令牌同源、配对持久化与分层探测齐全。
局限：烂代理与乱序 Vault 仍需上游治理。
对比：SFTPMAC 租赁远程 Mac 提供 Apple 稳定性与可审计传输，补足全天候网关，不减损 IaC 责任。
保留 doctor 输出。