1. 痛点拆解：容器「能 curl」不代表 CLI 走对了网卡
（1）WS 回环误配：CLI 默认指向 ws://127.0.0.1:18789 在宿主机成立，但在另一容器或 CI job 里会指向自己；Gateway 实际监听在 openclaw-gateway 服务名上时，仍写 127.0.0.1 等于永远自环。（2）配对与 Token 两条线混谈：pairing required 是会话未授权；unauthorized / token mismatch 是密钥不一致；混在一起改只会越改越乱。（3）环境变量覆盖配置文件：Compose 里一行 OPENCLAW_GATEWAY_TOKEN 可能与挂载卷里的 gateway.auth.token 冲突，表现为「改文件不生效」。（4）远程 Mac 双栈边界：launchd 起的进程与 compose 起的容器若共享同一端口声明，或同一数据目录被两实例读写，会出现间歇性「看似在线却不回」。
2. 症状—根因矩阵（先分层再改配置）
| 现象 / 日志关键词 | 优先假设 | 第一动作 |
|---|---|---|
1006 / 连接被重置 |
WS URL 指错主机或端口被占用 | 在发起 CLI 的同一网络命名空间里 nc -vz 目标主机:端口 |
1008 pairing required |
未完成控制面配对 | 打开 Gateway 控制面生成配对码；CLI 执行配对命令 |
token mismatch / unauthorized |
环境变量与配置文件不一致 | docker compose exec 打印相关 env；与卷内 JSON 对齐 |
| 偶发成功、多数失败 | 双实例争用数据目录或 token 轮换竞态 | docker ps + 卷挂载表；先缩为单实例 |
3. 落地五步走：把「能 ping 通」推进到「能完成一次 probe」
- 冻结网络命名空间：明确 CLI 从宿主机、sidecar 容器还是 CI runner 发起；把「谁连谁」画成一条箭头。
- 显式 WS Base：在对应环境写入
OPENCLAW_GATEWAY_URL（或项目文档规定的等价项），指向openclaw-gateway:18789或发布到宿主机的端口映射，而不是默认死写 127.0.0.1。 - 配对门禁：先完成 pairing，再测业务频道；把「未配对」与「Token 错」分两页台账记录。
- Token 单一真源：选择「只信环境变量」或「只信配置文件」之一作为团队规范；另一项必须与之相等或删除。
- 验收用
channels probe：在相同环境下跑通一次 probe，把日志片段与 compose 片段一并归档到工单。
4. Compose 对齐：何时考虑 network_mode: "service:openclaw-gateway"
当 CLI 与 Gateway 必须共享同一网络栈（例如避免默认桥接下服务名解析不一致）时，可将 CLI 容器挂到 Gateway 所在 network namespace。代价是端口与 localhost 语义更绕，必须在 README 画拓扑。另一种更常见做法是：CLI 仍在宿主机，仅 Gateway 在容器，此时应把 WS URL 指到映射后的宿主机端口，并在防火墙与反向代理层对齐 TLS 终止点。
5. 可引用阈值（评审向）：写进值班 Runbook 的三个数字
下列为讨论用量级，须用你的镜像与拓扑复测后替换：
- 若从 CLI 命名空间到 Gateway 端口的TCP 建连成功率低于 97%（100 次采样），先停功能排查，优先处理DNS/服务名/映射端口，不要先改模型路由。
- 若在单次配对窗口期内连续出现 3 次以上
token mismatch，应默认存在双真源（env 与文件），必须收敛为单一来源后再试。 - 当远程 Mac 上 Gateway 与宿主机 CLI 并发写同一状态目录导致锁等待超过 2.5s 出现在 p95 日志中，应拆分数据卷或把 CLI 迁入专用 sidecar。
6. openclaw logs 分层读法：从 transport 到 channel
先过滤 transport / websocket 相关行，再过滤 auth / pairing，再进入具体 channel。把三层截图附在工单里，比口头「我这边不行」更快收敛。与站内《官方 install.sh》连读时，可把「安装顺序」与「网络对齐」分成两次验收，而不是混在一次会议里口头通过。
| 层次 | 你要回答的问题 | 通过标准（示例） |
|---|---|---|
| L1 传输 | WS 是否握手成功 | 无 1006/1008 或已解释的预期关闭码 |
| L2 鉴权 | Token / pairing 是否一致 | 配对完成后无 unauthorized 循环 |
| L3 业务频道 | 渠道是否在线 | channels probe 对目标渠道返回可解释状态 |
7. 远程 Mac：launchd 与 Docker 的端口与目录边界
在远程 Mac 常驻时，常见组合是「Gateway 容器 + 宿主机 launchd 健康检查脚本」。必须写清：谁持有 18789、状态目录是 bind mount 还是命名卷、升级时先停谁。与《SSH / VNC 远程 Mac》连读时，把「远程桌面人机操作」与「无人值守 compose」分开排班，避免运维在 VNC 会话里手改文件而 CI 同时滚动升级。
8. FAQ
问：能不能只靠改 extra_hosts 解决？有时可以，但若根因是 token 双真源，改 hosts 只会把失败变成另一种间歇失败。
问：要不要把 Gateway 绑到 0.0.0.0？先读《Gateway 暴露面》做最小暴露；公网直连不是默认答案。
问：和 install.sh 路径冲突吗？不冲突但易混：install.sh 偏「从零到 probe」顺序；本文偏「已在 Docker 里」网络与鉴权对齐；两者应对照阅读。
9. 深度案例：「能 docker logs 看到 Gateway 已 listen」但仍 1008
2026 年社区反馈里，一类高频问题是：Gateway 在容器 A 正常 listen，但用户在容器 B 里跑 CLI，仍写 ws://127.0.0.1。这类问题在纸面上「显然」，但在多仓库、多 compose 叠加时极难靠口头传承。工程上应把「发起 openclaw 的网络命名空间」写进 README 的第一行，并在 CI 里用同一镜像跑一条 smoke：从 runner 容器 exec 一次 probe。
第二类问题是 OPENCLAW_GATEWAY_TOKEN 在 override 文件中被重复定义：本地开发者为了「临时试一把」加了一行 env，随后忘记删除，导致配置文件里的 token 永远不被读取。治理策略是：env 与文件二选一，并在 PR 模板里检查 diff 是否出现 token 相关 env。
第三类问题发生在远程 Mac：Time Machine 或同步盘把状态目录同步到第二台机器，两台机器各起一个 Gateway，表现为「频道偶发双应答」或「token 被轮换」。应明确状态目录不参与跨机同步，或改用集中式远程节点。
与《迁移与重配对》连读时，可把「换机」与「Docker 重建」分成两次演练：前者关心 workspace 与密钥备份；后者关心 compose 版本与卷 schema。混谈会导致回滚路径不清。
最后，Docker 不是「更省事」，而是更强约束下的可重复交付。当你能在工单里同时附上 compose 片段、env 打印、nc 结果与三层日志截图，团队才真正具备讨论「要不要上远程 Mac 专用节点」的资格。
10. 与 n8n / Webhook 集成时的额外注意
若你把 OpenClaw 与 n8n 串联，Webhook 入口往往在另一个容器或宿主机端口。此时「谁发起回呼」与「谁持有 Gateway token」必须一致；参阅站内 n8n Runbook 的分层退避段落，把 HTTP 与 WS 的故障分开记录，而不是把 502 与 1008 混在同一工单标题里。
11. 升级与回滚：先缩单实例再谈 feature
当上游发布带鉴权或 Gateway 协议变更的版本时，优先把环境缩成单 Gateway 单 CLI验证，再恢复多实例。双实例并行升级最容易制造「一半容器读新 schema、一半读旧卷」的半一致状态；与《OpenClaw 升级 breaking》类文章连读时，把 doctor 输出附在变更单上。
12. 收束：Docker 负责可重复，远程 Mac 负责可承诺
（1）当前方案的客观限制：Docker 拓扑把问题收敛为网络与卷，但团队若不在 README 固定「发起 CLI 的命名空间」，排障成本会指数上升；token 双真源会让「改配置」变成玄学。
（2）为什么远程 Mac 节点常常更省心：专用节点可把 Gateway、卷与 launchd 健康检查固化成镜像与 compose 版本对；与本机开发环境解耦，减少「我这边能连」式差异。
（3）与 MACGPU 场景的衔接：若你希望低门槛试用已对齐 compose 与端口的远程 Mac 作为 7×24 Gateway 承载，而不是让同事的笔记本当临时服务器，MACGPU 提供可租赁节点与帮助入口；下文 CTA 直达首页套餐与帮助（无需登录）。
（4）最后一道自检：对外宣称「已上线 OpenClaw」前，必须附上 channels probe 成功片段与 compose/env/token 对齐证明。
13. 实战补充：与 install.sh 与三栈对照的衔接
若你尚未跑通官方 install.sh 顺序，请先读对应文章建立基线；若已跑通但仍卡在 Docker，请回到本文矩阵从 L1 传输层重走。三栈对照文帮助你选择「CLI 放宿主机还是放容器」，避免为了追新而把 CLI 随意塞进 sidecar。