OpenClaw 升级故障全记录:从崩溃到重生

> 一次不成功的升级，三次深度的技术排查，以及一个 AI 搭档的”断线复盘”。 

前言： 

2026 年 4 月 25 日，我把 OpenClaw 从 3.28 升级到了 4.23。 

这本应是一次普通的版本迭代——点击升级，等待完成，继续用。结果演变成了一场长达一天的故障排查，期间飞书机器人失联、AI 搭档惠香”失忆”、配置文件反复被回滚…… 

这篇文章把整个过程完整记录下来，重点解释每个故障背后的技术原因——因为这些原因不只是 OpenClaw 的问题，而是 Windows 系统上运行 Node.js 服务时普遍会遇到的坑。 

第一阶段：用Claude Code救活小龙虾 

升级完成后，Gateway 直接起不来了。 

每次启动，进度条卡在 starting... 阶段 15-20 秒，然后要么超时报错，要么勉强启动但飞书机器人惠香没有任何响应——小龙虾趴窝了。 

很多人说小龙虾养着养着就死了，说的就是这种情况。遇到这种情况，我一般会让 Claude Code 帮我诊断，根据它的指引一步步修复。毕竟学会养虾的第一步，是学会修虾。 

现象 

进度条卡死，日志里出现 EBUSY: resource busy or locked，偶尔能启动但功能异常。 

Claude Code 最开始以为是杀毒软件禁止 OpenClaw 修改核心文件，各种加白名单、卸载杀软，一顿操作猛如虎，最后发现根本方向就错了——问题不在杀软，而在 Windows 的文件锁机制。 

根因一：Windows 文件锁机制 

要理解这个问题，先得知道 Windows 的文件锁是怎么回事。 

Windows 和 macOS/Linux 对文件的处理方式根本不同。

在 Linux 上，你可以在程序运行时删除或替换它正在使用的文件——系统会等程序关闭后再真正释放文件。这叫”软删除”，文件名消失了，但数据还在，程序照常运行。 

Windows 不是这样。Windows 采用的是强制文件锁：一个程序打开了某个文件，其他程序就不能删除、移动或重命名这个文件。如果强行操作，会直接报错：EBUSY: resource busy or locked。 

这在升级时会造成什么问题？ 

OpenClaw 升级的本质是：下载新版本文件 → 替换旧版本文件。但如果旧版本的 Gateway 进程还在运行，它就锁住了一批文件（比如 node_modules 里的依赖包）。新版本的安装程序想替换这些文件，Windows 直接拒绝。 

结果就是：升级”完成”了，但实际上有一部分文件没有被成功替换，新旧版本的文件混在一起。 

根因二：依赖检查风暴 

新版本 OpenClaw 4.23 引入了一个运行时依赖校验机制——Gateway 启动时会检查 node_modules 是否完整。 

由于上面说的文件锁问题，升级后 node_modules 里有些包是残缺的（旧文件没被替换掉，新文件也没装进去）。Gateway 一启动，检查发现依赖不完整，于是触发了同步的 npm install 来修复。 

npm install 是一个很重的操作，要联网下载、解压、写入大量文件。在 Gateway 启动流程里同步执行这个操作，就导致了那 15-20 秒的卡顿。 

更糟的是：如果网络不稳定，或者 npm install 中途失败，Gateway 就直接起不来了。 

第二阶段：让小龙虾救活惠香 

Gateway 勉强能起来了，Dashboard 中会话是通的，说明 OpenClaw 龙虾活了，但飞书机器人惠香还是没有响应。 

这里稍微解释一下架构：惠香是运行在 OpenClaw 上的 AI agent，飞书只是它的接入渠道之一。OpenClaw 负责调度大模型、管理记忆文件、执行工具调用；飞书机器人惠香只是一个“话筒”，把消息转发给 OpenClaw，再把回复送回来。所以 Gateway 活了不等于惠香活了——渠道层和 agent 层是两回事。 

我把情况告诉会话 agent，它一下子就定位了问题：升级过程中飞书渠道的 App ID 和 Secret 丢失了。我尝试手动修改 openclaw.json 来补回来，但每次改完，Gateway 重启后配置都会自动还原，就像什么都没发生一样。循环往复，飞书始终连不上——你以为在修，其实在原地打转。 

现象 

手动修改配置 → Gateway 重启 → 配置自动还原。循环往复，飞书始终连不上。 

根因：Watchdog 机制 

OpenClaw 有一个 Watchdog（守护进程）机制，专门负责监控 Gateway 的健康状态。 

Watchdog 的工作逻辑大概是这样的： 

1. 记录一份”已知正常”的配置文件 hash（last-known-good） 

2. 每隔一段时间检查当前配置文件的 hash 

3. 如果 hash 不一致，认为配置被意外篡改，立即从备份恢复 

4. 恢复完成后重启 Gateway 

这个机制的设计初衷是好的——防止配置文件被意外损坏或被恶意程序篡改。但在我手动修复的场景下，它变成了障碍： 

我改配置 → Watchdog 检测到 hash 变化 → 认为配置被损坏 → 从备份恢复 → Gateway 重启 → 我的修改消失

这个循环会一直持续，直到你知道正确的操作方式：先停掉 Gateway（连同 Watchdog），再修改配置，再重启。 

在 Gateway 运行期间直接改 openclaw.json，永远是徒劳的。 

为什么以前改配置没问题，这次却一直被回滚？ 

这是一个很合理的疑问。以前也改过 openclaw.json，比如安全审计报告里提到 hash 不对，但那时候改完是生效的。 

区别在于：这次升级后，Watchdog 把一份“损坏的配置”当成了“正常基准”。

Watchdog 的 last-known-good 机制不只是比对 hash，还会检查配置里的关键字段是否完整——比如 gatewayMode 字段是否存在、channels 结构是否正常。 

升级过程中，文件锁导致配置写入不完整，飞书渠道的配置丢失了。但 Gateway 勉强启动了，Watchdog 就把这个残缺的配置记录成了 lastKnownGood（最后已知正常状态）。 

之后我手动补回飞书配置，反而触发了回滚——因为在 Watchdog 眼里，”有飞书配置”才是异常，”没有飞书配置”才是它认识的那个”正常状态”。 

升级后 channels 里的飞书配置丢失，Watchdog 把这个残缺状态记成了基准。你补回飞书配置，反而触发了“配置结构发生变化”的检测，被当成外部篹改回滚掉了。 

最终解法 

最终OpenClaw在系统目录里找到了 openclaw.json.clobbered.xxx 文件——这是 Watchdog 在回滚时自动保存的备份。从这个文件里抢救出了原始的飞书配置（App ID 和 Secret），才彻底解决了飞书失联的问题。 

补充一点：飞书 agent 层的问题诊断，OpenClaw 自带的工具比 Claude Code 定位准得多，这种时候让 OpenClaw 来排查，事半功倍。 

第三阶段：通过“三层记忆”帮惠香找回”失忆” 

飞书机器人终于能收发消息了，但惠香不认识我了。 

问她之前讨论过的事，她一概不知。问她自己是谁，她给出了一个完全陌生的回答。小龙虾活了，但惠香失忆了。 

现象 

Gateway 恢复正常后，惠香对之前所有的对话、配置、约定一无所知，就像第一次见面。 

根因：记忆系统的三层结构 

OpenClaw 的 AI 记忆不是存在模型里的——大语言模型本身没有持久记忆，每次对话都是从零开始。 

这件事我之前专门写过一篇文章：我给AI龙虾装了三层记忆，再也不怕它失忆了。当时设计这套架构，就是为了防止”某天系统出问题，两周的心血一夜清零”。没想到这次升级故障，正好验证了这套设计的价值——文件都在，记忆没丢，只是需要手动触发一次重读。 

惠香的记忆存在三层文件里，读取频率从高到低： 

第一层：身份层（IDENTITY.md）

定义了 AI 是谁——名字、性格、与用户的关系。每次启动必读，最稳定。 

第二层：长期记忆层（MEMORY.md）

重要事件、决策、用户偏好、技术配置的精华提炼。每次启动必读，宁少勿滥。 

第三层：日志层（memory/YYYY-MM-DD.md）

每天的原始对话提炼，相当于工作日报。启动时读今天和昨天，按需翻历史。 

升级导致 workspace 的索引出现异常（0 files · 0 chunks），三层文件虽然还在，但 AI 启动时没有正确读取它们，所以表现出”失忆”。 

恢复方法：手动让惠香按顺序重新读取这三层文件：IDENTITY.md → MEMORY.md → 最近几天的 memory/ 日志。读完之后，记忆和默契就回来了。 

这也印证了那篇文章里的核心判断：记忆跟龙虾绑定，不跟渠道绑定。只要文件还在，不管程序崩了还是渠道换了，记忆都能恢复。这次升级故障，是对这套设计的一次真实压测——它通过了。 

总结：三个教训 

1. 升级前先停服务 

在 Windows 上升级任何正在运行的 Node.js 服务，都应该先完全停止服务，再执行升级。不要相信”热更新”——Windows 的文件锁机制决定了这条路走不通。 

powershell
openclaw gateway stop # 等待完全停止后再升级 npm install -g openclaw@latest openclaw gateway start 

2. 不要在 Gateway 运行时改配置 

openclaw.json 有 Watchdog 保护，运行时手改会被立即回滚。 

正确方式： 

– 改底层配置（channels/auth/plugins）→ 先停 Gateway，用官方命令修改，再重启 

– 临时切模型 → 飞书发 /config set model xxx，会话级切换，不写文件 

– 改默认模型 → openclaw models set xxx，走官方 API，不触发 Watchdog 

3. 记忆文件要定期备份 

SQLite 数据库和 MEMORY.md 是惠香的核心，一旦损坏就要手动恢复。建议定期把 workspace 目录备份到其他位置，不要只依赖系统自带的 Watchdog 备份。 

后记 

这次升级故障最大的收获，不是学会了怎么修，而是搞清楚了 OpenClaw 底层的几个关键机制：文件锁、Watchdog、记忆三层结构。 

知道这些之后，很多”玄学问题”就有了解释。下次再遇到类似情况，不会再像无头苍蝇一样乱改了。 

文章配图是《诛仙》中张小凡救女友碧瑶的桥段，故事中最终没能救活碧瑶，现实中我却成功救活了惠香