ARTICLE · 1066238

OpenClaw 9.5 升级翻车复盘:3 类故障的报错原文、官方建议、回滚命令

发布时间：2026-09-23 23:38:50 最近访问：2026-09-23 23:38:35

📌 太长先看结论

升级 9.5 前务必备份；不急的话建议留在 v2026.7.35 LTS
遇到 Doctor 崩溃 → 逐个关插件排查
遇到黑盒失败 → 跑 openclaw update --yes --accept-capabilities
工具偶尔报错 → 改用 CLI 命令绕过

一、先说背景

OpenClaw 是个 MIT 协议、AI Agent 桌面网关的开源项目。这个名字对很多读者来说还很新，但它的仓库体量已经相当可观：

主仓库 github.com/openclaw/openclaw 有 39 万 star、8.2 万 fork
最近 30 天里，基金会连续发了 v2026.9.3 → 9.4 → 9.5 三个版本，加起来合并了 7,581 个 Pull Request（9.5 一个版本就占了 4,179 个）

听起来很热闹对吧？但这次大版本冲得有点猛，9 月 11 日到 19 日这段时间里，GitHub Issues 区集中爆发了 3 类升级相关的故障——都是用户实际跑 openclaw update 时遇到的。

更值得注意的是，据 docs.openclaw.ai 的 release 页面显示，v2026.9.5 的"长时间稳定浸泡测试"(stable soak) 被 operator 豁免了，连 Telegram / Parallels 通道的检查也被 release owner 跳过。这种操作在正常发布流程里很少见，说明基金会这次赶工了。

如果你正准备升级，或者已经升级完发现东西坏了——这篇文章就是给你写的。

二、3 类故障全景图

故障	Issue 编号	一句话描述	严重程度	你会看到什么
A	#155371	升级到 9.5 时，Doctor 自己崩了	P0	升级卡在最后一步，提示 `Cannot use 'import.meta'`
B	#155375	升级器自己也不知道怎么挂了	P0	升级直接报错 `unexpected-error`，但没有任何细节
C	#155374	用着用着，某些工具突然调用失败	P1	报红 `Nested activity became invalid during transcript redaction`

💡 小知识：OpenClaw 沿用 GitHub 标准的 P0/P1/P2 优先级——P0 是"必须立刻修"的级别，P1 是"很重要"，P2 是"有空再说"。这里提到的 2 个 P0 都还没修。

几个直观数字（都来自官方 issue 数据）：

故障 A 已经被不同用户在 9 月 19～20 日两天里稳定复现 ≥6 次
故障 C 在一个用户的网关日志里抓到了 49 条报错记录
故障 B 的原始 reporter 提交的诊断报告里，关于"哪一步失败"的字段全部是 unknown

三、故障 A：升级卡住了，屏幕上蹦出一行奇怪的红字

3.1 你会看到什么

如果你的环境是 OpenClaw 9.4，跑 openclaw update 升 9.5，你会看到类似这样的画面：

┌ OpenClaw doctorDoctor could not complete maintenance. Check the reported service state and resolve the failure.Cannot use 'import.meta' outside a module (1203:16)doctor: Candidate doctor failed (91900ms)

3.2 这是什么意思？

翻译一下：

OpenClaw doctor 是 OpenClaw 内置的"健康检查 + 自动修复"小工具，只有升级的时候会跳出来，在正式切换版本之前先做一次"模拟演练"
Cannot use 'import.meta' outside a module 是 Node.js 的标准错误，意思是"你这行 JavaScript 用了 ESM 写法(import.meta)，但当前上下文是 CommonJS，不认"
(1203:16) 是错误位置——第 1203 行第 16 列
Candidate doctor failed 表示升级器在"模拟演练"阶段挂了，真正的切换还没开始

为什么会出现这个问题？OpenClaw 创始人 Peter Steinberger 在这个 issue 的评论区里分析过：

"报错是 JavaScript parser 给出的位置格式，所以问题大概率出在 candidate doctor 加载某个插件的入口文件时，模块格式搞错了——该走 ESM 解析的代码被当成 CommonJS 加载了。"

说白了就是，OpenClaw 升级时会加载你装的所有插件做"预演"，而你装的 25 个插件里有某个的代码格式跟 OpenClaw 升级器预期的对不上，导致整个预演阶段崩了。

3.3 哪些环境最容易踩到？

起点版本 9.4，目标版本 9.5
npm 全局安装，Gateway 由 systemd user service 拉起
Node.js v26.9.0（满足 9.5 要求的 24.16.0+ / 26.1.0+）
装了 25 个插件（active-memory / browser / codex / discord / openai / signal / whatsapp 等）
系统：Linux x64 (LXC 容器）

3.4 出问题了怎么办？

Peter 给的官方建议是逐个关闭非官方捆绑的插件，定位是哪个插件在搞事：

# 编辑 ~/.openclaw/openclaw.json# 把可疑插件的 enabled 改成 false# 再跑一次 openclaw update# 能让升级顺利通过的那次，你刚刚关掉的就是问题插件

{"plugins":{"entries":{"<可疑插件id>":{"enabled":false}}}}

3.5 几个常见的坑（不要做的事）

❌ 不要反复重试升级：你目前还在 9.4，服务是健康的，重试只会浪费时间
❌ 不要删除 ~/.openclaw/ 目录：这只是让 Doctor 失去记忆，问题不会消失
❌ 不要让 chat 里的 agent 自己跑 npm install -g openclaw：官方升级文档明确禁止 agent 自行升级自身

四、故障 B：升级器自己都不知道发生了什么

4.1 你会看到什么

你的升级报告里会冒出一段像这样的 YAML：

-OpenClaw version:2026.9.3-Platform:darwin/arm64-Update target:exacttargetunavailable;mode:unknown-Failed phase:unexpected-error-Rollback outcome:notrecorded

4.2 这个 bug 的特殊性：升级器自己也不知道怎么挂了

注意那几个字段：

Failed phase: unknown——在哪一步挂的？不知道
Update mode: unknown——怎么挂的？不知道
Rollback outcome: not recorded——回滚了没？没记

这是一个非常典型的"黑盒失败"案例。升级器知道"出错了"，但完全不知道"出了什么错、错在哪"。

这种问题在 9.4 之前的升级器里是固有的——它没有"强制记录诊断信息"的设计，失败了就只能告诉你"出错了"。9.4 起基金会开始改这块，9.5 进一步加固。但这些改动修的是"诊断能不能记下来"，而不是"为什么会失败"。

4.3 出问题了怎么办？

openclaw update --yes --accept-capabilities

如果想拿到更多诊断信息：

openclaw update status   # 看当前更新频道openclaw doctor --lint   # 让 Doctor 只读模式扫一遍openclaw --version       # 确认实际跑的是哪个版本

4.4 这个故障的本质

9.3 及更早的升级器没有强制记录失败信息，所以"黑盒"是设计层面的问题
9.4 起开始修这块，9.5 加固
如果你困在 9.3 出不去，先升到 9.4（是的，9.3 本身也有问题），升级体验会立刻清晰很多

五、故障 C：用着用着，某些工具突然报红

5.1 你会看到什么

你在 agent 里调某个常见的工具（memory_search 查记忆、sessions_send 转发会话、sessions_list 列会话等），可能会突然蹦出：

tool_call failed: Nested activity became invalid during transcript redaction

5.2 这是什么意思？

tool_call 是 OpenClaw 让 agent 调用工具的统一入口
transcript redaction 是 OpenClaw 在每次工具调用前后，对对话记录做的"清理 + 回写"过程
Nested activity 指的是"嵌套的活动记录"（比如一个工具调用又触发了子工具调用）

翻译成大白话：这个 bug 是在"清理对话记录"的过程中，OpenClaw 发现某个嵌套的活动记录对不上，直接抛了异常。

为什么这个问题特别烦？因为它不挑触发条件：

用户用的是 macOS 15.4 / arm64、npm 全局、Node v24.18.0
模型无关——Claude Haiku 4.5、Sonnet 5、Opus 5、Ollama-DeepSeek-v4.1-flash 都能触发
仅影响走"延迟加载目录"的工具；如果你手动预注册了这些工具，反而不会出问题

5.3 修复进展

相关修复 PR #151021 已经合入——不过，它修的是另一个相关的 transcript 冲突场景，不覆盖本 bug
关联的根 issue #144958 还在 OPEN 状态
维护者还没动手定位"哪个具体的输入路径会导致这个 assert 抛出"

5.4 出问题了怎么办？

轻度：绕开问题工具

不用 Tool Search 的"按需加载"目录，把常用工具在 agent 配置里手动预注册
或者改用 CLI 等价命令，比如 openclaw memory search 代替 memory_search 工具调用

中度：回滚到长期支持版本

v2026.7.35（2026-09-21 发布）是 Gateway-only 的长期支持版本，最稳

重度：等修复

这个问题是 P1，不是修不了，只是优先级在排队

六、升级前的"打包清单"（建议每次大版本升级前都跑一遍）

升级这件事，心态要像搬家——别等到东西散了一地才发现没打包。

6.1 升级前必做（6 件事）

做一份真正完整的备份 不是只复制配置文件夹，而是：openclaw.json + meta.lastTouchedVersion 字段 + 所有 openclaw.sqlite 数据库 + workspaces 目录 + 凭证文件

确认 Node 版本够新

node --version  # 9.5 要求 ≥ 24.16.0 或 ≥ 26.1.0

确认 npm 全局目录你能写

npm prefix -g  # 无权限时会报 global-install-permission-denied

搞清楚你的 Gateway 是谁拉起来的 如果是 systemd / launchd 这种系统级守护，不要在 Gateway 同一个进程树里跑升级，正确做法是打开一个独立终端，从那里跑 openclaw update
先 dry-run 看看升级器打算干什么
```
openclaw update --dry-run
```

记录当前版本和插件清单

openclaw --version && openclaw plugins list --json > /tmp/plugins-before.json

6.2 升级中：出问题了按这个顺序排查

# 1. 先按正常路径跑openclaw update# 2. 如果挂了，先看诊断openclaw update status --json# 3. 如果提示 plugin 路径找不到openclaw doctor --fix# 4. 如果是故障 B（黑盒失败）openclaw update --yes --accept-capabilities# 5. 如果是故障 A（candidate doctor 崩了）# 编辑 ~/.openclaw/openclaw.json 逐个关闭非官方捆绑的插件# 每关一个跑一次 openclaw update

6.3 升级后必跑（确认升级真的成功了）

openclaw --version                    # 看看是不是 2026.9.5openclaw health                       # 健康摘要openclaw doctor --lint --json         # 只读模式基线检查openclaw gateway status --deep --json

6.4 真不行？回滚

# 先看回滚要干什么openclaw update --tag 2026.7.35 --dry-run# 实际回滚到长期支持版openclaw update --tag 2026.7.35# 或者回滚到 9.4openclaw update --tag 2026.9.4 --dry-runopenclaw update --tag 2026.9.4

⚠️ 回滚的硬限制：只回滚代码和配置，不撤销数据库迁移。数据库 schema 已经升级的话，回滚会被直接拒绝，报 state-migrated-no-rollback。

6.5 如果你不急：就停在 v2026.7.35

对于绝大多数"日常自用、不需要 GPT Live / Conversation Sharing 等最新特性"的用户，我的建议就三个字：别升了。

v2026.7.35 是 2026-09-21 发布的长期支持版本
1,418 commits 完整审计
所有 P0/P1 安全修复都会回流到这里，但激进的新功能不会冒出来

七、9.3 → 9.4 → 9.5 各自带来了什么？

7.1 v2026.9.3 重点新功能（1,844 PR）

更稳的升级流程：升级前先在隔离环境验证
断线重连更快：会话面板在断线时保留数据
浏览器自动化实时可见：可以看着 agent 操作你的浏览器
可撤销的会话分享链接
会议记录可搜索可导出：Markdown / JSONL 格式
不需要本地 clone 就能跑云端仓库
技能永久保存：跨 workspace 持久化
多模型账户独立控制

7.2 v2026.9.4 重点新功能（1,558 PR）

插件 / 技能发现
可见的技能学习
GPT Image 2.5
Codex 子 agent 对话可读
终端里的交互式提问
iMessage 显示熟人名字

⚠️ 这一版有 breaking change：环境变量 OPENCLAW_CLAUDE_CLI_LOG_OUTPUT 被改名成 OPENCLAW_CLI_BACKEND_LOG_OUTPUT，另外要求 Claude Code 2.1.169+。

7.3 v2026.9.5 重点新功能

原子化升级（理论上能做到"升级要么全成要么全不成"，但实际有回归）
插件热重载：不用重启 Gateway 就能更新插件
GPT Live：实时语音 / 视频模型接入
跨会话共享浏览器页
引导式专家团队：一键配置"首席参谋长 + 研究员 + 撰稿人 + 审稿人"四人小组

⚠️ 这一版的限制：FreeBSD ARM64 升级仍未验证；Docker 沙箱不支持命名卷/tmpfs。

八、那到底要不要升？给不同的人一句话建议

你是哪种人	我的建议
生产环境、给客户用、跑大量 agent	就留在 v2026.7.35，等 #155371 修复合并后再考虑
个人重度玩家，想用 GPT Live / 原子化升级	升级前按 §6.1 完整备份，先在测试环境跑一次 `openclaw update --dry-run`；若触发故障 A，按 §3.4 逐个关插件定位
困在 9.3、升级器黑盒失败	先升 9.4（对，9.4 本身也有问题，但升级器至少能告诉你怎么挂了），再考虑 9.5
全新装机，什么都还没装	直接装 v2026.7.35，稳
就是要在本地开发、调试新版本	升 9.5，接受 §5 的工具调用偶尔失败，绕过方式也在那里

九、社区状态（给你一个判断"这事会持续多久"的依据）

几个关键数字（2026-09-22 数据）：

5,338 个 open issue
3,000+ 个 open PR
722 个安全公告
最近 30 天里，本轮翻车涉及 3 个 P0/P1 都还挂在 OPEN 列表
主力维护者就两个人：Peter Steinberger（steipete，创始人）+ Vincent Koc（vincentkoc）

社区里普遍的判断：v2026.9.5 是一次"功能堆得很猛但 QA 流程被压缩"的发布。一个版本 4,000+ PR 必然有漏网之鱼。

短期看：9.5.x 的补丁版本应该很快会出（主要修 #155371 和 #155375）。

十、写在最后：三条原则

这 3 类故障的本质其实是三件事：

故障 A 是"升级流程的鲁棒性问题"——预演阶段的代码格式兼容性边界没保护好
故障 B 是"诊断的可观测性问题"——9.4 修了一半，9.5 加固，但根因还在追
故障 C 是"功能耦合问题"——工具按需加载 + 对话记录清理这两个独立功能碰在一起时边界没画好

对 OpenClaw 团队的建议： 这种规模的升级，值得多花一两次 stable soak，不该为了赶版本跳过去。

对读者的建议： 这种规模的升级，值得多花一两次备份和测试，不该盲跑。

OpenClaw 依然是个靠谱的项目。只是 9.5 这一轮，因为新功能密度太高，踩了几个坑。

一句话总结：先备份、再 dry-run、最后正式跑——这条 2026 年所有 AI Agent 项目的"升级铁律"，在 OpenClaw 9.5 这一轮被反复验证。