2026 OpenClaw 网关排障 Runbook：从官方 command ladder 到 gateway install --force——解决「Runtime: stopped」、18789 端口占用与非 loopback 绑定鉴权失败（Mac 云 7×24）
升级或换机后最常见不是「模型坏了」，而是网关 Runtime 显示 stopped、18789 被旧进程占住、或把 bind 改成 lan/tailnet 却未配 gateway.auth。本文写给已在 Mac 云或自建 macOS 上跑 OpenClaw、需要可抄值班 Runbook 的运维：先按官方推荐的 command ladder 收集证据，再用 gateway status --deep 区分「CLI 配置」与「launchd 服务」漂移；明确何时应执行 gateway install --force 与 gateway restart；最后给出 Mac 云 7×24 下 plist 与日志路径、升级后三条验收与 FAQ。读完你应能把「凭感觉重启」收敛为可复现步骤。
本文要点
1. 导语：为何先 ladder 再谈模型与通道
OpenClaw 网关同时承载本地 RPC、控制面健康检查与通道插件：「通道不回」与「Runtime: stopped」表象相似，根因常在控制面。若跳过 openclaw status 与 openclaw gateway status 直接改模型或重登 IM，容易把「非 loopback 未配 gateway.auth.token」误判成「提供商 429」，把「旧 launchd 单元仍占 18789」误判成「Docker 网络坏了」。2026 年官方 troubleshooting 推荐的最低纪律仍是固定顺序：status → gateway status → logs → doctor →（必要时）channels status --probe；仅在证据指向服务元数据陈旧时，再进入 gateway install --force 与重启。下文先把四条高频痛点拆开，再给分流表与可执行步骤。
2. 痛点拆解：stopped、端口、bind/auth、服务漂移
- Runtime: stopped：常见于升级后 stricter 默认、
gateway.mode丢失或未设local；也可能只是 launchd 单元未加载成功，CLI 仍读旧 home 下配置。 - 18789 EADDRINUSE：旧网关进程、并行 Docker 映射或遗留 launchd 任务未退出；需用
lsof -i :18789与gateway status --deep对照「谁持有监听」。 - 非 loopback 绑定鉴权：将
gateway.bind设为lan/tailnet/custom时，若未配置gateway.auth或 token 漂移，日志会出现refusing to bind类提示；这与模型侧超时无关。 - CLI 与服务配置不一致：同一台 Mac 云既用终端调试又用 launchd 托管时，
Config (cli)与Config (service)路径不一致会导致「终端里好了、服务仍起不来」；gateway install --force用于把服务元数据与当前 profile 对齐。
3. 症状 → 根因分流表
| 现象 | 优先根因 | 第一反应（避免） |
|---|---|---|
Runtime: stopped 且日志提示 gateway.mode | 配置缺失或被覆盖 | 先重装整包依赖 |
| 启动即 EADDRINUSE 18789 | 旧进程/重复服务单元 | 改随机端口逃避 |
| 非 loopback 绑定失败 | gateway.auth 未对齐 | 把 bind 改回 0.0.0.0 却不设 token |
| CLI 正常、launchd 仍失败 | 服务安装漂移 | 仅手动 node 拉起而不修单元 |
install --force 前截取 gateway status --deep 与最近 200 行日志时间窗，便于区分一次性事故与配置漂移。
4. 落地步骤：ladder → deep → install --force（≥5 步）
- 跑官方 ladder：
openclaw status→openclaw gateway status→openclaw logs --follow（短窗）→openclaw doctor→openclaw channels status --probe；期望gateway status出现Runtime: running与探针 ok。 - 加深扫描：
openclaw gateway status --deep对照「CLI vs service」路径、重复单元提示、端口占用摘要。 - 修复绑定与鉴权：若必须非 loopback，补齐
gateway.auth.mode/gateway.auth.token与反向代理或 Tailscale 策略；否则先把 bind 收敛到 loopback 验证通路。 - 处理 18789 冲突：
lsof -i :18789定位 PID；优雅退出旧网关后再启动；Docker 场景核对是否双容器映射同一宿主机端口。 - 对齐服务元数据：当 deep 显示安装漂移或升级后单元未刷新时执行
openclaw gateway install --force，随后openclaw gateway restart，再用 ladder 前两条验收。
示例：在确认非生产调试可短暂停机时，可用下列顺序（按环境替换路径与用户）：
5. 可引用技术信息：端口、探针与 plist 字段
- 默认监听：网关默认 HTTP 端口 18789；变更后需在防火墙与安全组同步放行，并在 Mac 云安全组文档中登记。
- 探针期望：
gateway status健康时应能看到运行态与连通性探针 ok；若仅 CLI 正常而服务 stopped，优先查 launchd 退出码与日志目录挂载。 - launchd：常见 plist 由
gateway install写入用户LaunchAgents；升级后若域或 WorkingDirectory 改变，会导致「能装不能跑」，需用--deep提示清理重复单元。 - 日志窗口：排障时固定 2～5 分钟时间窗比对「配置变更」与「首次失败」时间戳，避免把历史 WARN 当成当前根因。
- 回滚策略：在执行
install --force前备份~/.openclaw下与网关相关的 json/yaml 与自定义 env；回滚时恢复文件再重启服务。
6. Mac 云与替代方案局限：为何长期仍推荐独占 Mac 节点
在共用 Linux VPS 或临时容器里硬跑网关，短期可验证功能，但会遇到三类长期成本：内核与 launchd 语义不一致导致排障手册无法复用到 macOS 真机；端口与卷权限漂移让 18789 与日志路径更难对齐值班；安全面更难做到「最小暴露 + 可审计 Token」与团队 SSH 习惯统一。相较之下，租赁 VPSMAC 的 M4 Mac 云节点能把网关与通道放在原生 launchd + 独占磁盘上，按本文 ladder 与 install --force 流程即可与站内 Docker Compose、生产加固长文衔接；需要收敛暴露面与 Token 轮换时，请继续阅读 OpenClaw 生产加固专题完成闭环。