2026 在 Mac VPS 上用 Docker 跑通 OpenClaw：Gateway Token、CLI 容器网络与「配对死锁」排障 Runbook
Compose 搬到 7×24 Mac VPS 后常见 token mismatch、1008 pairing、CLI 127.0.0.1:18789 拒绝连接。本文面向分容器托管网关与 CLI 的读者：五条根因、症状对照表、五步 Runbook（Token 冻结、双源对齐、网络缝合、配对出口、healthz+launchd），并链 Compose 7×24 与 网关 ladder。
本文要点
1. 痛点拆解：双源 Token、127 回路、配对死锁与卷权限
上游 Docker 文档与 docker-setup.sh 默认假设「人与脚本在同一网络命名空间内点下一步」，Mac VPS 上无人值守时最常见的五类断裂如下：
- 环境变量静默覆盖配置文件：容器内若存在
OPENCLAW_GATEWAY_TOKEN，其优先级可能覆盖openclaw.json中gateway.auth.token，表现为 UI 粘贴「看起来对」的 token 仍报 mismatch。 - CLI 与网关分容器时的 127.0.0.1 误连：
openclaw-cli默认尝试ws://127.0.0.1:18789，但该地址指向CLI 容器自身的回环，而非网关容器；日志常见ECONNREFUSED或1006异常关闭。 - 配对死锁：网关绑定
lan后，控制面与 CLI 互相要求对方先被批准，若文档未给出「先用带 token 的 dashboard URL 或 CLIdevices approve」的明确顺序，会在 1008 上循环。 - bind 模式与 Docker 网桥语义混用：
gateway.bind=loopback与「跨容器访问」目标冲突；切到lan后若未同步调整 CLI 的可达 URL，会出现「网关日志已 listen，但外部握手仍失败」。 - 卷权限与 uid 1000：镜像内进程常以 node uid 1000 写入挂载目录；宿主机若用 root 生成文件，会在 Mac VPS 上表现为间歇性写入失败，进一步放大 token 持久化失败。
2. 对照表：症状、根因与首选命令
下表可直接贴进值班手册「首屏 triage」；与站内 生产加固：暴露面与 Token 对照阅读可补齐长期策略。
| 症状（日志/CLI） | 高概率根因 | 首选动作（可审计） |
|---|---|---|
| token mismatch | 环境变量与 json 双源不一致 | grep 对齐；setup 前固定 hex token |
| 127.0.0.1:18789 拒绝 | CLI 与 gateway 分命名空间 | network_mode: service:openclaw-gateway 或 GATEWAY_URL 指服务名 |
| 1008 配对循环 | 互等批准 | dashboard --no-open；devices approve |
| 健康检查飘红 | 未探端口 | HTTP 探 /healthz 与 /readyz |
| 写入又丢 | 卷或 uid | bind 到 VPS 盘；chown -R 1000:1000 |
单一真源原则：在 Mac VPS 上首次部署前执行
export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)，将同一字符串写入 .env、Compose 的 gateway 与 CLI 环境块，并在 onboarding 全过程中只粘贴这一份；禁止在排障中途让脚本重新生成第二份 token。
3. 五步 Runbook：从预置 Token 到可值班验收
- 冻结 token：在任意管理终端生成 hex，写入版本库外的
.env.production，并在变更单记录「镜像 tag + token 指纹（前 8 位）」。 - 对齐双源：启动前用只读命令确认
gateway.auth.token与OPENCLAW_GATEWAY_TOKEN完全一致；若使用多阶段 compose，检查 CLI service 是否继承了同名环境变量。 - 修正网络：若必须分容器，优先让 CLI
network_mode: service:openclaw-gateway；否则为 CLI 设置GATEWAY_URL=ws://openclaw-gateway:18789并保证 DNS 在 compose 网络内可解析。 - 打破配对环：在网关容器内执行
openclaw dashboard --no-open，用打印的 URL 完成控制面；再于 CLI 侧devices approve；全程保留审计日志片段。 - 探活与 launchd：主机侧用
curl -fsS http://127.0.0.1:18789/healthz与readyz写入 plist 的SuccessfulExit判定；与站内 Compose 7×24 文对齐restart与资源上限，避免「网关进程在但 WS 未就绪」的假绿。
Compose 片段示例（仅示意网络缝合，生产请按官方仓库模板合并）：
services:
openclaw-gateway:
image: ghcr.io/openclaw/openclaw:latest
environment:
OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
ports:
- "18789:18789"
openclaw-cli:
network_mode: "service:openclaw-gateway"
environment:
OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
4. 可引用技术信息：端口、UID 与探活路径
- 端口：默认网关 WebSocket/控制面监听
18789；任何健康检查脚本应命中真实监听地址而非仅docker ps状态。 - UID：官方镜像常见运行用户 uid
1000；Mac VPS 宿主机目录权限应与之对齐，避免「配置已写入但容器重启后丢失」的假性修复。 - 探活：
/healthz表示进程存活，/readyz更贴近可接受 WS 的就绪语义；值班手册应写明先后次序与超时。
5. 与 Compose 7×24 与原生网关 Runbook 的阅读顺序
Compose 语言先读 7×24；网关/CLI 真相源分歧再读 ladder。笔记本演示在无 UI 的 Mac VPS上会放大双源 token 与分容器网络成本。Docker 比 launchd 多一层排障心智；要独占 Apple Silicon、固定出口、可预期并发承载网关，租赁 VPSMAC M4 Mac 云更易把卷、plist 与 Compose 写进同一手册。开通自动化见 90 秒 API 文。