平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“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/[email protected] 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/[email protected] info --all
这一步能够很直观地验证当前环境到底处于什么状态。
迁移完成后，关键设置变成了下面这种结构：
plugins.allow中包含openclaw-larkplugins.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/[email protected] 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 升级飞书插件这件事上，希望这篇记录能帮你少绕一点弯路。
飞书插件官方文档： （链接已移除）
结合项目来看，到此这篇关于升级 OpenClaw 到最新版 + 迁移飞书官方插件的踩坑记录的文章就介绍到这了,更多相关OpenClaw飞书插件升级内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多兼容脚本之家！