gateway.token 迁到 gateway.auth.token、launchd 载入的旧 plist 仍指向上一版二进制、以及把 gateway.bind 改成 lan 却未同步鉴权。本文给升级前快照清单、openclaw doctor 与 gateway status --deep 的分诊顺序、split brain 修复步骤、Tailscale 与 ssh -L 两种远程打开 18789 的可复现命令块，以及 gateway install --force 的适用边界；与站内 安装排障清单、常驻稳定性 两篇交叉阅读可形成完整运维闭环。2026 年升级后五条高频故障：把 split brain 误判成「模型不稳」
OpenClaw 近版本收紧了本地 Gateway 的绑定与鉴权策略：当 gateway.bind 离开回环且未提供有效 gateway.auth.token 时，进程会拒绝启动；而 CLI 若仍指向用户目录下较新的全局安装，launchd 却从另一前缀拉起旧二进制，就会出现「doctor 无阻塞、RPC probe 失败」的 split brain。第三类问题是升级后仍保留废弃键名 gateway.token，新 schema 静默忽略导致仪表盘反复未授权。第四类是把状态目录放在企业同步盘或网络卷上，升级写配置与守护进程读配置竞态，表现为间歇性 401。第五类是在云厂商安全组放行 18789 却未在应用层完成 token 与 bind 组合，公网扫描流量放大日志噪声，排障时被误判为上游模型超时。
下面五条把上述现象落成检查顺序，避免在未核对监督元数据与 PATH 之前就去调模型温度或换 API Key。若你尚未完成初装，请先按 安装排障清单 走通 onboard 与 launchd，再回到本篇处理升级与远程访问。
键名漂移：仅升级 npm 包而未把 gateway.auth.token 写入 launchd 可见的配置路径，Dashboard 与 CLI 各自读到不同片段。
二进制双轨：which openclaw 与 plist 内 ProgramArguments 第一项不一致，升级后新字段只被一侧识别。
绑定与鉴权组合不完整：lan 或等价非回环监听未配 token，Gateway 直接退出；日志里常见「refusing to bind」类签名。
端口表无 owner：18789 被遗留调试进程占用，gateway install --force 前未清理，导致「已重启仍 EADDRINUSE」。
远程访问走裸公网：在未完成隧道或边缘 ACL 的情况下把监听暴露出去，触发安全策略与无意义重试。
认清这五类根因后，才能把升级问题收敛到可审计路径：先冻结版本与配置快照，再用 doctor 与 deep status 对齐 CLI 与服务视图，最后才选择隧道或受控 bind 策略。
对照表：回环-only、LAN 加 token、以及隧道访问三种远程打开 Dashboard 的方式
云 Mac 上通常优先让 Gateway 只监听 127.0.0.1，由工程师通过 SSH 本地转发或 Tailnet 暴露给可信终端；这与把 18789 直接挂在公网网卡上是不同的威胁模型。下表用于写进 Runbook 第一页，避免值班时在「要不要改 bind」上临时争论。
| 模式 | 适用 | 前置条件 | 常见坑 |
|---|---|---|---|
| loopback | 单用户本机或仅 SSH 入内后本地打开 | 默认最简；token 可选 | 忘记隧道仍从外网 curl 健康检查失败 |
| lan + token | 内网固定网段探针或受控 Wi‑Fi | 必须配置 gateway.auth.token 与防火墙最小放行 | token 未写入 plist 环境导致服务侧为空 |
| SSH -L / Tailscale | 跨公网运维、零信任边界 | SSH 密钥轮换与 MagicDNS 规划 | 本地端口冲突、断线后未自动重连脚本 |
| 命令或信号 | 健康含义 | 异常时优先怀疑 |
|---|---|---|
openclaw doctor | 配置 schema、token、端口、监督一致性初筛 | 旧键名、PATH、同步盘锁文件 |
openclaw gateway status | Runtime 与 RPC 探针摘要 | 进程起但 RPC 不可达、token 漂移 |
openclaw gateway status --deep | 扫描重复 install、系统级与用户级单元冲突提示 | 双轨 launchd、残留 schtasks 或旧 plist |
先对齐「谁在跑、读哪份配置、监听哪个地址」，再谈远程；否则隧道只会把错误广播到更多终端。
官方排障文档建议从 openclaw status、gateway status、openclaw logs --follow、openclaw doctor 的组合开始；在云 Mac 上应额外记录镜像里 Node 与全局前缀是否与 plist 一致，避免容器化或 golden image 更新后 silent drift。
token 迁移与 split brain：把「配置写进去了」升级成「监督进程也读到了」
当你确认 ~/.openclaw/openclaw.json 已出现 gateway.auth.token 却仍 401 时，下一步不是生成第十个 token，而是验证 launchd 工作目录与 OPENCLAW_STATE_DIR 是否与交互 shell 相同。云镜像有时会为 CI 用户与登录用户准备两套 home，plist 若引用错误用户，就会出现「我 cat 文件明明有 token」的错觉。
若 doctor 提示新旧二进制 split，按文档先修正 PATH 再执行服务侧重装元数据；不要在旧二进制仍被监督拉起的窗口里反复 config set，否则会出现 meta 版本戳与运行时不一致的 guard。
openclaw doctor openclaw config get gateway.auth.token openclaw gateway status --deep openclaw gateway install --force openclaw gateway restart
提示：在变更窗口同时备份 openclaw.json、plist Label、以及 openclaw --version 输出；回滚时按「版本 + 监督 + 配置」三元组恢复，而不是只回文件。
需要跨团队移交时，把上述四条命令的输出粘进与 常驻稳定性 文中心跳与 pm2 段落并列的值班页，避免口头描述「昨晚我改过一个端口」。
六步可复现：从本机 loopback 到安全远程打开 18789
下列步骤假设 Gateway 已能在云 Mac 本机 loopback 访问；若尚未达成，请先回到安装清单完成 onboard 与 daemon。再执行远程段落，避免把网络问题伪装成鉴权问题。
本机验收：在服务器上 curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/ 或文档推荐的健康路径，确认 loopback 正常。
择一路径：仅运维个人笔记本访问优先 ssh -L 18789:127.0.0.1:18789 user@cloud-mac；多成员长期访问评估 Tailscale 与受限 ACL。
消冲突：本地若已占用 18789，改用 ssh -L 19000:127.0.0.1:18789 并在浏览器指向本地高端口。
对齐 token：隧道场景下浏览器仍按 Gateway 要求提交 token；把值放在密码管理器而非聊天。
记录断线策略：为长时间会话准备 autossh 或等价重连，避免无人值守任务误以为 Gateway 离线。
写回变更单：把 bind 模式、隧道命令、端口 owner 记入与区域/规格同一工单；需要扩规格时用 订购入口 留痕。
三条上线口径与何时动用 gateway install --force
版本戳一致：配置 meta.lastTouchedVersion 与运行中 openclaw --version 同向；逆向升级需单独评估，不要混用 force 掩盖。
监督元数据单一来源：同一主机默认只保留一套用户级 Gateway 单元；出现 deep 扫描提示的重复项时先禁用多余单元再 force。
force 边界：用于 plist 内端口与当前 config 漂移、或 doctor 明确建议刷新监督；不替代完整密钥轮换与安全组审计。
注意：在未读完日志与 doctor 结论前反复 force，可能把临时端口占用问题升级成监督循环重启，反而放大中断窗口。
与「长期占用同事笔记本当 Gateway 宿主机」相比，在可按区、按档、按租期拆单的 KVMNODE 云 Mac 上固定 OpenClaw，更容易把二进制版本、plist、token 与隧道命令写进同一张变更单；笔记本仍要面对合盖休眠与系统更新。对要把 Gateway 可观测性、升级回滚与续租节奏写进项目周报的团队，独占裸金属节点配合多地区选点，通常比散落设备更易执行：先在目标区短租跑通升级与隧道验收，再决定是否上到 M4 Pro 与更长周期，用 定价页 与 帮助中心 固定留痕。