OpenClaw 升级 到最新版 + 迁移飞书官方插件的踩坑记录

最近把一台已经跑过旧版 OpenClaw 的升级到 4.20，过程中最大的坑还不是升级 OpenClaw 本体，反而是历史遗留的飞书插件状态。

原本想只要拉最新仓库、执行 pnpm install、重新启动就够了；但如果本机 ~/.openclaw 里已经残留了旧版飞书插件 feishu-openclaw-plugin，升级后就很容易出现插件 ID 不匹配、健康检查异常、飞书鉴权报错等问题。

这篇文章记录一下我这次从旧环境升级到可用状态的完整过程，给后面碰到类似问题的人一个可复用的参考。

一、环境背景

我的场景比较典型：

• 机器上以前已经安装过旧版 OpenClaw
• 历史数据目录在 ~/.openclaw
• 代码仓库已经拉到最新
• 已经执行过 pnpm install
• 飞书侧以前装过旧版官方插件

升级前的直觉通常是：既然仓库已经更新，直接重新构建、重启就好。

但真实情况是：旧版飞书插件和新版官方插件不是简单覆盖关系，而是一次迁移关系。

二、问题现象

一开始我遇到的现象并不统一，但本质都指向同一个问题：旧插件残留。

典型表现包括：

• openclaw 可以启动，但某些命令执行失败
• openclaw health 里 Feishu 不正常
• 提示类似 plugin id mismatch
• 网关启动后飞书能力异常
• 旧的插件目录和配置还残留在 ~/.openclaw/extensions

核心问题是：旧插件 feishu-openclaw-plugin 还留在环境里，而新版安装路径已经切到 openclaw-lark。

三、先升级 OpenClaw 本体

第一步仍然是把 OpenClaw 本体升级到最新，并确保当前代码能正常构建。

我本地做的事情包括：

pnpm install
pnpm build

如果你是从源码运行，这一步很重要，因为有些旧的 dist 构建产物和新依赖版本不一致时，会出现看起来很奇怪的运行时错误。

构建完成之后，建议先跑一遍修复命令，把 ~/.openclaw 里的历史状态整理一下：

openclaw doctor --repair --non-interactive

这一步的作用是先把基础环境整理干净，比如：

• 清理过期锁文件
• 修补配置
• 修复部分状态目录问题
• 确认网关服务状态

四、真正的关键：用飞书官方安装器做迁移

真正解决问题的关键步骤，是运行飞书官方插件安装器，而不是只靠 OpenClaw 主程序本身。

根据飞书官方文档，我最终执行的是：

npx -y @larksuite/openclaw-lark@2026.4.7 install --version 2026.4.7 --tools-version 1.0.37

这条命令非常关键，因为它会主动检查旧环境，必要时执行迁移。

我本次实际执行时，它输出了非常关键的一段信息：

Migrating: Old plugin feishu-openclaw-plugin detected.
Running uninstall command for feishu-openclaw-plugin...

也就是说，安装器明确识别出了旧版插件残留，并自动执行了卸载。

随后它完成了几件事：

• 卸载旧插件 feishu-openclaw-plugin
• 删除旧插件对应的配置项、安装记录、allowlist 条目和插件目录
• 安装新版官方插件 openclaw-lark
• 复用已有的飞书机器人配置
• 自动重启网关服务

安装成功后，终端里会看到类似这样的结果：

Installed plugin: openclaw-lark
Restart the gateway to load plugins.
...
Restarted systemd service: openclaw-gateway.service
OpenClaw is all set.

五、迁移后的配置状态

安装完成后，我又执行了一次：

npx -y @larksuite/openclaw-lark@2026.4.7 info --all

这一步可以非常直观地验证当前环境到底处于什么状态。

迁移完成后，关键配置变成了下面这种结构：

• plugins.allow 中包含 openclaw-lark
• plugins.entries.openclaw-lark.enabled = true
• 内置 feishu 插件为 enabled = false
• 旧的 feishu-openclaw-plugin 已经被清理掉

这点非常重要。

很多人看到“内置 feishu 被禁用”会以为出问题了，但在这条官方迁移路径里，这其实是正常结果。因为现在真正负责飞书能力的是新版官方插件 openclaw-lark，而不是历史上的旧外部插件，也不是当前仓库内置的社区 feishu 插件路径。

六、最终验证：看 openclaw health

判断这次升级是否真正完成，最直接的命令只有一个：

openclaw health

我最终看到的关键输出是：

Feishu: ok

只要这一行是 ok，基本就说明下面几件事同时成立：

• OpenClaw 本体已经升级成功
• 网关服务已经正常运行
• 飞书官方插件已完成迁移
• 飞书插件与当前配置可以正常协同

如果这里依旧报错，那问题才需要继续往飞书权限、应用配置、用户授权方向排查。

七、我这次升级的最终结论

这次踩坑之后，我的结论很明确：

如果机器上以前安装过旧版 OpenClaw，并且 ~/.openclaw 里残留了旧版飞书插件，那么升级时不要只更新仓库和依赖。正确做法是：先升级 OpenClaw 本体，再运行飞书官方安装器完成官方插件迁移。

换句话说，这不是一次简单的“版本升级”，而是一场“历史插件迁移”。

如果你只做了下面这些动作：

git pull
pnpm install
pnpm build

然后就直接期待飞书恢复正常，往往是不够的。

真正闭环的动作应该是：

openclaw doctor --repair --non-interactive
npx -y @larksuite/openclaw-lark@2026.4.7 install --version 2026.4.7 --tools-version 1.0.37
openclaw health

八、给后来人的建议

如果你也在做类似升级，我建议按下面顺序操作：

• 先升级 OpenClaw 仓库代码并安装依赖
• 重新构建，确保本体可运行
• 运行 openclaw doctor --repair
• 使用飞书官方安装器执行插件迁移
• 用 openclaw health 验证最终状态

额外提醒两点：

• 如果安装器检测到旧插件并自动迁移，不要手动再把旧插件重新启用
• 如果你在公开场景贴过 gateway.auth.token，记得立即重新生成并重启网关

可执行：

openclaw doctor --generate-gateway-token
openclaw gateway restart

九、结尾

这次升级里最容易误判的一点，是把问题归咎于“配置不对”或者“权限不全”，但实际根因是旧版飞书插件残留带来的迁移问题。

只要官方安装器已经完成旧插件卸载、新插件安装，并且 openclaw health 明确显示：

Feishu: ok

那这次升级才算真正完成。

如果你正好也卡在旧版 OpenClaw 升级飞书插件这件事上，希望这篇记录能帮你少绕一点弯路。

飞书插件官方文档： https://bytedance.larkoffice.com/docx/MFK7dDFLFoVlOGxWCv5cTXKmnMh

到此这篇关于升级 OpenClaw 到最新版 + 迁移飞书官方插件的踩坑记录的文章就介绍到这了,更多相关OpenClaw飞书插件升级内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！