OpenClaw 9.5 升级翻车复盘及避坑指南

一、先说背景

OpenClaw 是个 MIT 协议、AI Agent 桌面网关的开源项目，由 OpenClaw 基金会（美国 501(c)(3) 非营利组织）维护。这个名字对很多读者来说还很新，但其实它的仓库体量已经相当可观:

• 主仓库 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 doctor
Doctor 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 列。看到这种数字就说明错误来自某段被 OpenClaw 加载的代码
• Candidate doctor failed 表示升级器在"模拟演练"阶段挂了，真正的切换还没开始

为什么会出现这个问题?OpenClaw 创始人 Peter Steinberger 在这个 issue 的评论区里分析过，大意是:

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

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

3.3 哪些环境最容易踩到?

根据这位用户的反馈:

• 起点版本 9.4(commit 3a9d69d)
• 目标版本 9.5(commit ec9c1a13)
• 安装方式: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 给的官方建议是逐个关闭非官方捆绑的插件，定位是哪个插件在搞事:

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

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

如果你愿意帮官方加快修复，可以跑一下 openclaw plugins list --json,把插件清单附到 issue #15535——7` 那条下面.

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: exact target unavailable; mode: unknown
- Failed phase: unexpected-error
- Rollback outcome: not recorded

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

注意那几个字段:

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

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

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

4.3 出问题了怎么办?

如果你撞到这个，Peter 给的建议是:

openclaw update --yes --accept-capabilities

如果你想拿到更多诊断信息，可以跑这几个命令并把结果贴到 issue 里:

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

4.4 这个故障的本质

• 9.3 及更早的升级器没有强制记录失败信息，所以"黑盒"是设计层面的问题，不是某个具体 bug
• 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

打开 OpenClaw 网关日志看，这种报错可能被记了 N 条。

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 都能触发
• 仅影响走"延迟加载目录"的工具;如果你手动预注册了这些工具，反而不会出问题

一个用户的网关日志里 9 月 21 日当天就抓到了 37 条同样的报错，前后累计 49 条，说明这不是偶发。

5.3 修复进展

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

5.4 出问题了怎么办?

这里给你三个层次的选择，从轻到重:

轻度:绕开问题工具

• 不用 Tool Search 的"按需加载"目录，把常用工具在 agent 配置里手动预注册（在 plugins.entries 下加 preload)
• 或者改用 CLI 等价命令，比如 openclaw memory search 代替 memory_search 工具调用,openclaw sessions list --json 代替 sessions_list

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

• v2026.7.35(2026-09-21 发布）是 Gateway-only 的长期支持版本，基金会保证 P0/P1 安全修复都会回流到这里，但激进的新功能不会冒跑
• 这条对生产环境最稳

重度:等修复

• 这个问题是 P1,不是修不了，只是优先级在排队。如果你愿意等，可以订阅 #155374 收通知

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

升级这件事,心态要像搬家 —— 别等到东西散了一地才发现没打包。下面这套清单是我从官方升级文档、回滚文档和上面 3 个 issue 的实操建议里拼出来的。

6.1 升级前必做(6 件事）

1. 做一份真正完整的备份

• 不是只复制配置文件夹，而是:openclaw.json + meta.lastTouchedVersion 字段 + 所有 openclaw.sqlite 数据库 + workspaces 目录 + 凭证文件
• 升级器自带的"自动配置副本"≠ 完整备份，别混淆

1. 确认 Node 版本够新

• 跑 node --version,9.5 要求 ≥ 24.16.0 或 ≥ 26.1.0
• 版本不够老的话，会直接被 node-runtime-preflight 拦下来

1. 确认 npm 全局目录你能写

• 跑 npm prefix -g 看路径，无权限时会报 global-install-permission-denied

1. 搞清楚你的 Gateway 是谁拉起来的

• 如果是 systemd / launchd 这种系统级守护,不要在 Gateway 同一个进程树里跑升级,否则会撞 managed-service-preflight
• 正确的做法:打开一个独立终端，从那里跑 openclaw update

1. 先 dry-run 看看升级器打算干什么

• openclaw update --dry-run,看它列出的阶段里有没有 migration rehearsal 这一步（有的话，如果你装了 25 个以上插件，大概率会撞故障 A)

1. 记录当前版本和插件清单

• 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.5
openclaw health                     # 健康摘要
openclaw doctor --lint --json       # 只读模式基线检查
openclaw gateway status --deep --json

6.4 真不行?回滚

如果你升完发现 9.5 实在不能用，回滚命令是这样:

# 想要"先看回滚要干什么"
openclaw update --tag 2026.7.35 --dry-run

# 实际回滚到长期支持版
openclaw update --tag 2026.7.35

# 或者回滚到 9.4(你升级前的版本)
openclaw update --tag 2026.9.4 --dry-run
openclaw update --tag 2026.9.4

回滚的硬限制（官方明确写了）:

• 只回滚代码和配置,不撤销数据库迁移。如果数据库 schema 已经升级了，回滚会被直接拒绝，报 state-migrated-no-rollback
• 不要单独复制 *.sqlite 文件去覆盖 —— 文档原话:"Never copy only the main .sqlite file from a live WAL database: committed data can still be in -wal"
• 也不恢复分离的 $include 文件

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

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

• v2026.7.35 是 2026-09-21 发布的长期支持版本
• 1,418 commits 完整审计
• 所有 P0/P1 安全修复都会回流到这里，但主分支那些还在冒跑的新功能不会冒出来
• 对生产环境、给客户用的、跑大量 agent 编排的,这是最稳的选择

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

这一节给你一个版本演进的鸟瞰图，如果你赶时间可以跳过。

7.1 v2026.9.3 重点新功能(1,844 PR)

• 更稳的升级流程：升级前先在隔离环境验证，有界修复尝试，明确区分"恢复"和"升级成功"
• 断线重连更快：会话面板在断线时保留数据，配对通过后自动恢复
• 浏览器自动化实时可见：你可以看着 agent 操作你的浏览器，不再黑盒
• 可撤销的会话分享链接：给出去的链接可以随时作废（虽然已经下载过的副本收不回）
• 会议记录可搜索可导出：Markdown / JSONL 格式，Web 端 4 MiB 上限
• 不需要本地 clone 就能跑云端仓库：远程会话可以在云上直接跑，checkpoint 会保留工作成果
• 技能永久保存：你学到的 Skill 跨 workspace 持久化
• Mac 原生浏览器 Tab：Mac 上 Tab 切换对话时不再丢页面
• 多模型账户独立控制：可以在设置里给每个模型账户单独配置
• Issue / PR 渲染成小芯片：GitHub 链接显示更紧凑

7.2 v2026.9.4 重点新功能(1,558 PR)

• 插件 / 技能发现：更容易找到社区贡献的插件和技能
• 可见的技能学习：对话过程中"教会"agent 一个技能，以后能直接调用
• 云端 worker 控制：对云上跑的会话有更多管控能力
• GPT Image 2.5：图像生成模型接入
• Codex 子 agent 对话可读：在任务面板里能看到子 agent 的完整对话
• 终端里的交互式提问：agent 能在终端向你提问
• 启动时自动找 Node：不再污染你系统的 Node
• 配置只读模式：OPENCLAW_CONFIG_READONLY=1,给外部托管配置用
• Telegram 富消息格式保留：列表/引用里的链接保持可点击
• 语音会话可委派：语音模式下可以委派子任务，主对话保持连贯
• iMessage 显示熟人名字：通讯录里有名的人会显示真名（如果有）
• macOS 原生内存搜索：通过 brew install sqlite + Bun 启用

⚠️ 这一版有 breaking change:环境变量 OPENCLAW_CLAUDE_CLI_LOG_OUTPUT 被改名成 OPENCLAW_CLI_BACKEND_LOG_OUTPUT,如果你自己写过脚本要用这个变量，记得改;另外要求 Claude Code 2.1.169+。

7.3 v 2026.9.5 重点新功能

• 原子化升级(Atomic Updates):理论上能做到"升级要么全成要么全不成",但 #155371 / #155375 表明实际有回归
• 插件热重载：不用重启 Gateway 就能更新插件
• 可撤销的对话分享：和 9.3 那条会议分享类似，这次扩展到普通对话
• GPT Live：实时语音 / 视频模型接入
• 跨会话共享浏览器页：多个 agent 可以共用一个浏览器实例
• 对话归档：把历史对话归档存放
• 引导式专家团队：一键配置"首席参谋长 + 研究员 + 撰稿人 + 审稿人"四人小组
• FreeBSD CLI 安装：FreeBSD 系统也能装 OpenClaw 了
• 大刀阔斧的 UI 重整：5 大类共 200+ 个 sidebar / composer / 长对话渲染 / 模型选择器 / 仪表盘的 PR

⚠️ 这一版的限制:FreeBSD ARM64 升级仍未验证;Docker 沙箱不支持命名卷/tmpfs;none 鉴权模式仍拒绝移动端配对码。

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

你是哪种人	我的建议
生产环境、给客户用、跑大量 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 列表
• 仓库里大量 issue triage 由 ClawSweeper / roboclaw-bot 自动化处理（带 clawsweeper:bulk-filed 标签的多半是 bot 提的）
• 主力维护者就两个人:Peter Steinberger(steipete,创始人）+ Vincent Koc(vincentkoc)

社区里普遍的判断：v2026.9.5 是一次"功能堆得很猛但 QA 流程被压缩"的发布。基金会人手有限（全职核心维护者就两位）,一个大版本 4,000+ PR 必然有漏网之鱼。

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

长期看：如果你看重稳定，留在 v2026.7.35 这条 LTS 线路是最稳的。

十、写在最后：三条原则

如果你读到这里，你会发现这 3 类故障的本质其实是三件事:

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

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

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

OpenClaw 基金会的赞助方有 Amazon / OpenAI / Red Hat / 密歇根大学等，基础设施由 Blacksmith / Convex / GitHub / NVIDIA / Vercel 提供，大方向上依然是个靠谱的项目。只是 9.5 这一轮，因为新功能密度太高，踩了几个坑。

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