教程 · 维护
OpenClaw 9.4 升 9.5 失败后按报错码逐个处理
升级报错以后，第一条该敲的命令是 openclaw update status，看清这次失败落在哪种原因上：doctor-failed、managed-service-preflight、runtime-verification-failed，还是收尾阶段的「Doctor could not enter maintenance」。这几种的第一步处理各不相同，对上号再动手。
状态目录这时候先别恢复。官方排障页写明：更新失败后，第一反应不该是恢复状态，应当在保留现有状态的前提下，把确认能用的代码重新装回来（官方更新排障文档）。平时怎么升级、怎么回滚，在《OpenClaw 升级、回滚与彻底卸载》里；这篇接的是它后面那一截：升级已经报了错。
排障页里有好几段是专门冲着已发布的 2026.9.4 更新器写的。从 9.4 往上升，执行升级的是你机器上已经装好的那个旧更新器，它身上的限制会带进这次升级。时间线：GitHub 上 2026.9.4 发布于 9 月 11 日，2026.9.5 发布于 9 月 19 日；截至 9 月 23 日，npm 上 latest 和 beta 都指向 2026.9.5，extended-stable 是 9 月 21 日发布的 2026.7.35。
用 openclaw update status 认出原因码
在跑 Gateway 的那台机器上执行：
openclaw update status在输出里找这次失败的原因码；收尾阶段失败的，找 finalize:doctor 后面的报错原文。开着控制台的，也可以去 Control UI 的 Settings → Updates 看，官方文档写明那里会保留最近一次尝试的时间、原因码（reason code）和失败的那一步。拿到之后对照这张表：
| 你看到的 | 对应情况 | 先做的动作 |
|---|---|---|
| doctor-failed | 更新过程中的 doctor 检查没过 | 在 Gateway 主机上跑 openclaw doctor，处理完再重试 |
| managed-service-preflight | macOS 上由 2026.9.4 Gateway 发起的升级，交接成功，激活时失败 | 从独立终端跑一次 openclaw update |
| runtime-verification-failed | 约 300 秒停下；快照准备和候选检查共用五分钟时限 | 看下文五分钟时限一节，重试一次仍失败就手动升级 |
| finalize:doctor · Doctor could not enter maintenance | 还有 Gateway 占着所选的状态目录 | 停掉占着状态目录的 Gateway，再跑 openclaw update repair |
表里没列到的原因码，排障页有专门的 Reason codes 一节。
doctor-failed：回到 Gateway 主机上跑 doctor
官方对 doctor-failed 的处理是：在 Gateway 所在的主机上运行 openclaw doctor，把它报出的问题逐项处理掉，然后重试更新。
openclaw doctor「Gateway 所在的主机」要照字面执行。Gateway 跑在远程服务器上，就登录那台服务器去跑，别在自己电脑上跑完就当查过了。
doctor 报几项就处理几项，每处理完一项再跑一遍 doctor，看它还报不报；清干净了再重试更新。9 月 23 日 GitHub 上新开的 #156194，就是一台 macOS 机器在 2026.9.4 上报的 doctor-failed。
managed-service-preflight：macOS 上由 Gateway 发起升级时撞上的
官方把这种情况写在 macOS 下：2026.9.4 的 Gateway 通过它的 update.run 动作或 /update 发起升级，交接能成功，到激活那一步以 managed-service-preflight 失败（官方更新文档）。
处理办法是由这套 OpenClaw 的主人，在 Gateway 进程树之外的独立终端里，用同一个账户、同一份安装、同一套状态和配置，跑一次：
openclaw update- 账户不换：平时是哪个 macOS 用户在跑 Gateway，就在哪个用户下敲这条命令，别切到别的用户去执行。
- 终端要独立：「outside the Gateway process tree」按本站理解，就是自己在 Mac 上新开一个终端窗口来敲，别让龙虾用它的 shell 工具代跑——那个 shell 是从 Gateway 那边拉起来的，还挂在它的进程树里。
- 安装和状态对得上：机器上装过两份 OpenClaw、或者指定过别的状态目录的，要在出问题的那一份上跑，别换到另一份。
如果 2026.9.4 更新器是直接拒绝、原因写着 managed-service-preflight，官方的做法是在 Gateway 之外的 shell 里跑手动更新，把命令里的 <target> 换成拒绝信息里写明的确切目标版本。那条命令在官方更新文档里，照抄时只改这个占位符。
9 月 20 日的 #153547 是一台 macOS 机器从 2026.9.4 升 2026.9.5 时撞上这个原因码，报告里的 Node 是 26.5.0，在官方要求的范围内。FreeBSD 的读者另记一句：官方在 FreeBSD 部分写明，--no-restart 修不好旧的准入检查。
runtime-verification-failed：卡在五分钟时限上
已发布的 2026.9.4 更新器，给快照准备和候选检查共用一个五分钟的时限。runtime-verification-failed 在 300 秒上下出现，撞上的就是这道线。9 月 19 日的 #153055 报的正是状态库太大、每次卡在 300 秒升不上去。
这种时候别做这几件事：
- 把
--timeout调大再试。官方原句写明，就算给了更大的--timeout，已装的更新器仍让快照和候选检查共用这段时限。 - 为了压进五分钟去清状态库。删掉的东西，升级成功了也回不来。
- 同一条命令原样连刷。旧更新器的时限不会因为多试几次变长。
管着一批机器的，排障页有一节 Published 2026.9.4 on large agent fleets，动手前先读。单台机器重试不过，看后面的手动升级。
收尾报「Doctor could not enter maintenance」
这条出在 finalize:doctor，也就是升级的收尾阶段。官方的解释是：还有一个 Gateway 占着所选的状态目录，doctor 进不了维护状态。
官方给的处理顺序是：先解决占用问题，再跑 openclaw update repair，然后用 openclaw update status --json 和 openclaw gateway status --deep 查还有没有挂着没做完的迁移、记录下来的警告，以及当前健康状况。占着目录的多半就是还在跑的 Gateway，先把它停掉：
openclaw gateway stop
openclaw update repair
openclaw update status --json
openclaw gateway status --deepupdate repair 做的是把更新的收尾重跑一遍，核心包它不重装。官方还写明：别去删锁文件硬闯维护状态。
手动升级：官方给 root 所有的 Linux 全局安装写的步骤
runtime-verification-failed 重试一次仍在 300 秒上下失败，可以改走这套手动步骤。这套流程直接用 npm 装包，不经过已装 2026.9.4 的更新器，而卡在 300 秒上下的正是那个更新器自带的时限。
官方步骤（官方更新方式文档）：
openclaw gateway stop
sudo /usr/bin/npm i -g openclaw@latest --allow-scripts=openclaw
openclaw gateway install --force
openclaw doctor --fix
openclaw gateway restart第二行的 sudo 配 /usr/bin/npm，是官方针对 root 所有的 Linux 系统全局安装写的：用系统自带的 npm，全局目录归 root 管。
本站提醒：Node 是用 nvm 或 Homebrew 装的，用你自己那份 npm，不加 sudo，第二行换成：
npm i -g openclaw@latest --allow-scripts=openclaw--allow-scripts=openclaw 这个参数适用于 npm 12 或 npm 11.16 以上；npm 11.15 及更早的版本，把它整个去掉再跑。Node 本身也要达标：24.x 线要 24.16 以上，或者 26.1 以上。当初是按哪种方式装的记不清了，翻《本地部署 OpenClaw 龙虾：三平台照抄教程》对一下。
五步里任何一步报错，就停在那一步，把完整输出存下来，别跳过去接着敲。走完这五步也未必就升上去了：原因码背后的问题没处理干净，照样可能卡在 doctor --fix 或重启那一步。
升完怎么确认升上去了
在跑 Gateway 的那台机器上依次执行：
openclaw --version
curl -fsS http://127.0.0.1:18789/readyz
openclaw plugins list --json
openclaw gateway status --deep --json
openclaw doctor --lint --json| 命令 | 看什么 |
|---|---|
openclaw --version | 版本号是不是你要升到的那一版；装的是 latest 的，按 9 月 23 日的 npm 标签，版本号应是 2026.9.5 |
curl -fsS …/readyz | 不报错退出，表示就绪接口返回了成功状态；-f 会让失败的 HTTP 状态直接报错。18789 是官方示例里的端口，你的 Gateway 不在这个端口就换成实际端口 |
openclaw plugins list --json | 升级前装过的插件是不是都还在列表里 |
openclaw gateway status --deep --json | Gateway 服务是否在跑、深度检查有没有报异常 |
openclaw doctor --lint --json | doctor 的检查结果，升级后还遗留的问题会列在这里 |
五条都过了，这次升级才算落地。还有一条过不去，排障页的 Support diagnostics 一节是给要找人求助的情况准备的；GitHub 上 #153547 和 #156194 的标题都写成「Update failure: 原因码 (2026.9.4)」，拿自己的原因码搜，能找到同样处境的报告。
常见问题
- 更新失败后能直接恢复状态目录吗？
- 恢复状态放在后面，第一步是在保留现有状态的前提下，把确认能用的代码重新装回来，这是官方排障页的要求。真要回滚，先读该页的 Rollback boundary 一节。
- 把 --timeout 调大能解决 300 秒超时吗？
- 对已装的 2026.9.4 更新器没用。它让快照准备和候选检查共用五分钟时限，官方写明给了更大的 --timeout 也一样。
- nvm 装的 Node 手动升级要加 sudo 吗？
- 本站建议不加，用你自己那份 npm。官方命令里的 sudo /usr/bin/npm 是针对 root 所有的 Linux 全局安装写的。
- 现在升级该升到哪个版本？
- 从 2026.9.4 往上升，升到 2026.9.5：截至 2026 年 9 月 23 日，npm 上 latest 和 beta 都指向它，手动升级命令里的 openclaw@latest 装的就是这一版。extended-stable 指向的 2026.7.35 版本号比 2026.9.4 低，从 9.4 装它是降级，动手前先读排障页的 Rollback boundary 一节。