更新和回滚

更新后

当更新完成但网关已关闭、通道为空或模型调用失败并显示 401 时使用。

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

查看以下内容：

• Update restart 位于 openclaw status / openclaw status --all 中。待处理或失败的切换包括下一个要运行的命令。
• Channels 下的 plugin load failed: dependency tree corrupted; run openclaw doctor --fix：通道配置仍然存在，但插件在通道加载之前注册失败。
• 重新身份验证后的 Provider 401：openclaw doctor --fix 检查过时的每个代理 OAuth 身份验证影子并删除旧副本，以便所有代理解析当前共享配置文件。

准备模型运行时发布超时

如果启动报告 prepared model runtime publication (...) timed out，则括号内的详细信息会标识待处理阶段以及工作区准备期间的代理。收集该错误以及 openclaw gateway status --deep 和启动日志。

即使网关进程使用很少的 CPU，ambient credentials 阶段也可以等待插件的外部登录检查。对于Claude CLI，以相同环境的网关用户运行claude auth status --json。 Startup 在工作区之间共享此检查；大型名册不应为每个代理启动一个本机登录子进程。仅成功的 /health 响应并不能确定模型运行时发布已完成。

分裂脑安装与较新配置保护

当网关服务在更新后意外停止，或者日志显示某个 openclaw 二进制版本比最后写入 openclaw.json 的版本更旧时使用。

OpenClaw 用 meta.lastTouchedVersion 标记配置写入。只读命令可以检查由较新的 OpenClaw 编写的配置，但进程和服务突变拒绝从较旧的二进制文件运行。阻止的操作：网关服务 start/stop/restart/uninstall、强制服务重新安装、服务模式网关启动和 gateway --force 端口清理。

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

回滚后协议不匹配

当降级或回滚后日志持续打印 protocol mismatch 时使用。此时运行的是较旧的 Gateway，但某个较新的本地客户端进程仍在以较旧 Gateway 无法支持的协议范围重新连接。

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

查看以下内容：

• Gateway 日志中的 protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>。
• openclaw gateway status --deep 中的 Established clients: 或 openclaw doctor --deep 中的 Gateway clients：连接到网关端口的活动 TCP 客户端，在 OS 允许的情况下使用 PID 和命令行。
• 命令行指向你回滚前的较新 OpenClaw 安装或包装器的客户端进程。

使固定：

1. 停止或重启 gateway status --deep 中显示的那个失效的 OpenClaw 客户端进程。
2. 重启嵌入 OpenClaw 的应用或包装器：本地仪表盘、编辑器、应用服务器辅助进程，或长期运行的 openclaw logs --follow shell。
3. 重新运行 openclaw gateway status --deep 或 openclaw doctor --deep，确认失效客户端的 PID 已消失。

不要让较旧的网关接受较新的不兼容协议。协议碰撞可以保护电汇合约；回滚恢复是一个 process/version 清理问题。