2026_OPENCLAW
UPGRADE_
BREAKING_
DOCTOR_AUTH_V2.

// 痛点：一行 npm i -g openclaw@latest 后 Gateway 起不来、频道全静默、技能装一半报错——多半是 breaking 目录/环境变量/设备鉴权 没对齐。结论：本文给出升级前快照清单、openclaw doctor --fix 适用边界、.moltbot→~/.openclaw 与 OPENCLAW_* 迁移对照、设备鉴权 v2 常见失败模式，以及远程 Mac launchd 下环境变量继承的踩坑与回滚路径。结构：痛点｜对照表｜五步 Runbook｜阈值｜远程矩阵｜FAQ｜案例｜收束与 CTA。延伸阅读：《安装路径三栈》《Gateway 常驻与回滚》《迁移与重配对》《暴露面收敛》《无回复与 doctor》《套餐》。

安全配置与变更管理概念示意

1. 痛点拆解：升级不是「覆盖二进制」这么简单

（1）状态目录漂移：历史版本可能把配置落在 ~/.moltbot 或旧前缀环境变量下；新版本统一向 ~/.openclaw 与 OPENCLAW_* 收敛。若只升级包体不迁数据，Gateway 会读到半套旧配置，表现为「进程在跑但频道全哑」。

（2）doctor --fix 不是万能键：它能修一批常见漂移，但对频道凭证过期、反代路径变更、自定义 skills 路径仍需人工决策；盲目 --fix 可能改写你刻意保留的本地覆盖。

（3）设备鉴权 v2：nonce 签名与客户端版本门槛提高后，旧设备或旧 CLI 会出现握手成功但消息不进工作流；在远程 Mac 上若 launchd 未继承与交互 shell 相同的环境，会放大为「本机 OK、服务器不行」。

2. 迁移对照表：目录、环境前缀与鉴权代际

维度 升级前常见形态 升级后目标形态
配置与密钥根 ~/.moltbot、散落 CLAWDBOT_* / MOLTBOT_* ~/.openclaw 为单一真源；统一 OPENCLAW_*
launchd / systemd plist 里写死旧路径或旧 env plist 与当前 shell profile 对齐；显式 export OPENCLAW_*
设备鉴权 legacy v1 签名仍被部分客户端使用 v2 nonce 流程；CLI/设备端同代升级

3. 落地五步走：可复现升级 Runbook

  1. 冻结快照：打包 ~/.openclaw（或旧目录）、workspace、launchd plist、当前 openclaw --version 与频道 webhook 配置截图；标注 Git 提交或包版本号。
  2. 只读诊断：先跑 openclaw doctor（不带 --fix）导出文本；再跑 status / gateway / logs 各一轮，保存输出。
  3. 受控修复：在测试副本目录上试 doctor --fix；确认 diff 后再在生产路径执行；禁止 SSH 里随手改完不存档。
  4. 环境对齐：把仍依赖旧前缀的 shell 脚本、CI、launchd 全部扫一遍；用 grep -R 搜遗留字符串并替换为 OPENCLAW_*。
  5. 烟测与回滚：频道发送探针消息、触发一个最小 skill、检查 Gateway 指标；失败则按《Gateway 回滚》文章路径恢复镜像/包与 plist。
# 示例：在改动前导出 doctor（勿在生产直接粘贴未知 fix） # openclaw doctor > /tmp/openclaw-doctor-before.txt # openclaw doctor --fix # 仅在已读懂提示与 diff 后执行 # launchctl print gui/$(id -u)/your.label # 核对 EnvironmentVariables 块

4. 可引用阈值（评审向）

写进变更单可用的讨论量级（需结合你的版本说明替换）：

  • 若升级后连续 3 次 doctor 报同类配置漂移且影响频道接入，应暂停继续升小版本，先完成目录/环境前缀一次性迁移，而不是堆补丁。
  • 当设备鉴权相关错误在日志中占比超过20%且集中在单一客户端版本，优先统一升级该客户端到支持 v2 的构建，而不是反复重置 Gateway。
  • 远程 Mac 上若 launchd 任务与交互 shell 的 OPENCLAW_* 差集非空，且差集包含密钥或基址 URL，必须在上线前清零；否则视为未通过门禁。

5. 远程 Mac Gateway：环境继承决策矩阵

现象 优先怀疑 动作
SSH 登录后手动启动正常，launchd 启动失败 plist 未注入 PATH / API key / OPENCLAW_* 在 plist EnvironmentVariables 显式写入；避免依赖 ~/.zshrc
升级后仅某一频道无回复 Webhook URL 或签名校验与新版默认不一致 对照官方升级说明重配；参阅《无回复与 doctor》
技能装得上但执行报权限 workspace 路径或沙箱边界随版本收紧 复核 skills 目录权限与只读挂载；参阅《暴露面收敛》

6. FAQ：--fix 会不会动我的 workspace？

问：doctor --fix 和重装哪个更安全？在有快照的前提下，先 fix 再定向修通常快于盲重装；无快照时优先复制整个状态目录再操作。

问：Docker 安装也需要迁 ~/.openclaw 吗？取决于你是否把配置挂载进卷；宿主机与容器只能有一个真源，混用 bind-mount 时最易出现「改 A 不生效」。

问：v2 鉴权失败后能临时降回 v1 吗？不建议在生产长期降级；应升级客户端。若必须临时验证，限定在隔离环境并设到期拆除。

7. 深度案例：从「全静默」到「可签字的变更记录」

某团队在远程 Mac 上跟随小版本连续升级两次后，Gateway 日志显示进程健康但 Slack 事件不再进入工作流。复盘发现三处叠加：plist 仍引用旧二进制路径、OPENCLAW_GATEWAY_TOKEN 留在 shell profile 而未写入 launchd、Slack App 的签名校验与新版默认 header 不一致。

单独修任何一处都会「偶发恢复」，直到按 Runbook 做环境差集清零与频道重配对才稳定。该案例说明：升级问题常被误判为「模型坏了」或「频道坏了」，实则是配置拓扑未随版本契约更新。

将每次升级的 doctor 输出、plist diff 与频道探针截图入库后，二次升级耗时从数小时降到数十分钟，且可审计。

与大规模 2.0 叙事不同，本清单聚焦高频小版本断裂；若你仍处 MoltBot 代际，请先完成《迁移与重配对》再使用本文阈值。

安全面在升级后常被遗忘：新版可能默认收紧绑定或技能执行边界，应结合《暴露面收敛》复核监听与卷挂载。

建议在变更窗口内对 openclaw 可执行文件做 shasum 归档，并在工单中写明「从 A 到 B」；当回滚时不仅降版本，还要核对 plist 是否仍指向正确路径。多用户机器上，若 Gateway 以 UserName 与登录用户不一致运行，密钥链与文件 ACL 会表现为「间歇性」故障，应在烟测前用 whoami 与 plist 的 UserName 对齐检查。

若团队同时使用 Homebrew 与 npm 全局 两套 openclaw，务必在 PATH 中固定唯一入口，否则 doctor 修的是 A 路径、launchd 启的是 B 路径，日志里会出现令人困惑的「版本已最新但仍报旧错」。

8. 可观测性：升级窗口内的最小指标集

建议在变更窗口记录：Gateway 启动退出码、频道探针成功率、技能冷启动耗时中位数、鉴权失败日志条数/小时。四项同时异常时优先怀疑环境前缀与路径；仅鉴权异常上升则切到客户端版本矩阵。

信号 含义 下一步
doctor 持续提示同一键缺失 真源未统一到 ~/.openclaw 停升版本，先完成目录迁移
手动 OK / launchd 不 OK 守护进程环境漂移 比对 plist 与交互 shell 的 env 差集
仅夜间任务失败 cron/launchd 与登录会话不同用户 核对运行用户与密钥可见性

8.1 与 CI、预发环境与版本冻结：别让「流水线最新」拖垮生产 Gateway

许多团队在 CI 里用 npm i -g openclaw@latest 做每日构建，却把与生产不同的 Node 大版本、不同的默认 shell、以及缓存目录一并写进制品描述。结果是：CI 报告 green，生产 launchd 仍在旧 minor 上跑，二者对 doctor 的提示文本都不一致。正确做法是在流水线中钉死 digest 或精确 semver，并把「可执行文件绝对路径 + shasum」写进构建产物元数据；生产变更单只引用该元数据，而不是「latest」这个词。

预发（staging）Gateway 若与生产共用同一 Slack Workspace，务必使用独立 Bot 或独立频道，否则一次误发的 webhook 重放可能污染生产审计。预发的 launchd plist 建议复制生产 plist 后仅替换密钥与监听端口，再跑完整烟测；若预发 plist 结构比生产「多一行 EnvironmentVariables」，说明生产已经漂移，应反向合并而不是只在预发上修。

版本冻结窗口内，禁止并行存在两套 OPENCLAW_CONFIG_ROOT 语义：有人在 /etc/environment 写一份、有人在用户目录写一份，会在守护进程重启时随机胜出。升级周应临时冻结这类全局注入，改由单一 plist 或单一 systemd drop-in 作为真源，并在工单附上 diff -u。

若你使用 Ansible/Chef 等配置管理，注意它们往往在登录会话与守护进程两条路径上各渲染一次模板；两次渲染若时间不同步，会出现「中午 OK、夜里又坏」的错觉。把模板版本号打进 plist 注释行，便于和 CM 的 commit 对齐追溯。

最后，升级不是只面向人类操作者：任何调用本地 openclaw 的定时健康检查脚本也要随大版本切换同步升级，否则旧脚本可能解析不了新 CLI 子命令的退出码，把 healthy 判成 critical，触发误重启雪崩。

9. 收束：Windows/Linux 教程同样要先对齐契约

（1）当前方案的客观限制：在非 Mac 环境跟随 OpenClaw 升级时，服务管理器与路径差异更大，若不固定状态目录与 env 真源，排错成本高于 Mac。

（2）为什么远程 Apple Silicon Mac 常常更省心：与官方文档、launchd 示例及图形/自动化工具链的一致性更高，减少「双栈配置脑裂」。

（3）与 MACGPU 场景的衔接：若你希望低门槛试用常驻 Gateway 节点并由同一拓扑承接升级验证，而不是在笔记本上反复折腾守护进程，MACGPU 提供可租赁远程 Mac 与公开帮助入口；下文 CTA 直达首页套餐与帮助（无需登录）。

（4）最后一道自检：未附快照与 doctor 输出的升级，视为未完成变更闭环。

10. 与安装三栈、Docker 生产的衔接

npm 全局、Docker Compose 与 pnpm 源码三套路径的数据目录并不相同；升级断裂时先确认你正在修的是哪条链路的真源。参阅安装三栈对照与 Docker 生产部署实践，避免跨路径混拷配置。