2026 年把 OpenClaw 迁到常驻网关，常见翻车点是openclaw update、官方 install.sh 与多套二进制路径叠加，让 openclaw.json、环境变量与 launchd 彼此漂移。下文写清：update 与 install.sh 边界；npm 全局 与 源码 并存时谁在被守护进程调用；回滚清单；以及多地区 M4 云 Mac 灰度里 openclaw health 的验收口径。可直接粘进内部 wiki 变更模板，和发版日历对齐。
一、openclaw update 与官方 install.sh：先定边界再动手
update 偏同管线 semver 递进；install.sh 更像重建安装布局，目录或 Node 假设变了时别只跑 update 以免半新半旧。顺序：1）导出 which openclaw、版本、openclaw.json、plist；2）LB/DNS 摘流留 canary；3）小版本 update，大版本按文档重跑 install.sh；4）doctor 与最小探针后再接流量。plist 里旧二进制绝对路径是高发坑，分层排错见 了解更多：OpenClaw 裸机 macOS 网关 launchd 与鉴权运维 FAQ。
二、npm 全局与源码目录并存：让 PATH 与守护进程只认一套
终端正常、守护进程报 command not found 或旧子命令，多半是 交互 PATH 与 launchd 环境 不一致。生产请在 plist/单元里写死 PATH并用绝对路径调二进制；开发可用 npm link，上线收敛到单一前缀。并行安装时留意 EACCES、Apple Silicon 上误装 x64 原生包、以及 node_modules/.bin 抢在 brew 之前。升级前用非交互会话跑 openclaw --version，用户与网关进程保持一致；必要时在工单里附上 launchctl print 截取，避免「我本地能复现」式扯皮。
三、典型报错与回滚清单（打印贴在值班区）
每次升级先冻结快照，故障按逆序恢复；值班交接时口头过一遍路径。
- 配置与密钥：
openclaw.json、令牌环境变量、TLS、自定义hosts。 - 进程模型：plist/unit、Label、参数、
WorkingDirectory。 - 二进制：npm 版本、源码
git rev-parse HEAD、lockfile；Docker 记镜像 digest 与 compose 哈希。 - 回滚：
git checkout上一 tag 或还原 npm；plistunload/load；LB/DNS 回旧池；有快照先还原盘。
401/403 查令牌与代理证书；端口占用 查旧进程或重复 Label；子命令缺失 多为 PATH 指错前缀。先切回稳定流量再 diff。
四、多地区云 Mac 灰度与 openclaw health 验收
在新加坡、东京、首尔、香港、美东、美西各留一台 M4 云 Mac 作 canary：同一 openclaw.json，先小流量或单渠道，看首 token、429/5xx 与重连。把 openclaw health 写进发布门禁：进程、端口、上游 TLS、磁盘与日志可写皆绿再抬权重；对照错误指纹判断是否单区域网络或镜像漂移。门禁脚本建议与生产池同一仓库版本，避免 canary 探针字段落后于线上。
五、业务 FAQ（浓缩版）
- 跳过 canary？ 不建议；至少留旧版一台对照 health 字段。
- 白天 hotfix：摘流 → 备份 json/plist/digest → 单台升 → health → 小流量 → 全量。
- 云 Mac 与笔记本：开发用本机，生产只在云 Mac 固定前缀与固定用户安装。
在 vpszap 云上，这一切更简单
升级演练需要可复现真机与多地低延迟：vpszap 独享物理 M4 Mac Mini，无虚拟化争抢；约五分钟开通，SSH+VNC 便于 canary 上钥匙串与 GUI 一次性授权；按天/周/月/季、无长约，可分区短租双版本并对照 openclaw health。
若要把本文清单落在可横向扩展的多地环境上，vpszap 云端 Mac mini 是低开销起点。
