更新和回滚

更新之后¶

当更新完成但 Gateway 宕机、通道为空或模型调用返回 401 时使用。

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

请查找：

• openclaw status / openclaw status --all 中的 Update restart。待处理或失败的交接会包含下一步要运行的命令。
• Channels 下的 plugin load failed: dependency tree corrupted; run openclaw doctor --fix：通道配置仍然存在，但插件注册在通道加载之前就失败了。
• 重新认证后的 Provider 401：openclaw doctor --fix 会检查过期的按智能体划分的 OAuth 认证影子副本，并移除旧副本，使所有智能体都解析到当前共享配置文件。

预置模型运行时发布超时¶

如果启动时报告 prepared model runtime publication (...) timed out，括号中的细节会指明待处理的阶段；在准备 workspace 期间，还会指明其对应的智能体。请将该错误与 openclaw gateway status --deep 及启动日志一起收集。

ambient credentials 阶段可能会等待插件的外部登录检查，即使 Gateway 进程的 CPU 占用很低。对于 Claude CLI，请以 Gateway 用户身份并在相同的环境中运行 claude auth status --json。启动过程会在多个工作区之间共享此检查；较大的名单不应为每个智能体启动一个 native-login 子进程。单独的 /health 成功响应并不能确认模型运行时发布已经完成。

脑裂安装与新版配置保护¶

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

OpenClaw 会在配置写入时标记 meta.lastTouchedVersion。只读命令可以检查由较新版 OpenClaw 写入的配置，但进程和服务级变更操作会拒绝从旧版二进制运行。被阻止的操作包括：gateway 服务的启动/停止/重启/卸载、强制重新安装服务、服务模式下的 gateway 启动，以及 gateway --force 端口清理。

which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion

1. 修复 PATH

修复 PATH，让 openclaw 解析到较新的安装版本，然后重新执行该操作。

2. 重新安装 gateway 服务

从较新的安装版本重新安装目标 gateway 服务：

openclaw gateway install --force
openclaw gateway restart

3. 移除过期的包装器

移除仍然指向旧 openclaw 二进制的过期系统包或旧包装器条目。

回滚后的协议不匹配¶

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

openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw 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：这些是连接到 Gateway 端口的活动 TCP 客户端；在操作系统允许的情况下，会显示 PID 和命令行。
• 命令行指向你回滚前所用的较新版 OpenClaw 安装或包装器的客户端进程。

修复方法：

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

不要将旧版 Gateway 设置为接受更新的不兼容协议。协议版本提升用于保护线上通信契约；回滚恢复实际上是一个进程/版本清理问题。