最近把一臺已經(jīng)跑過舊版 OpenClaw 的升級到 4.20，過程中最大的坑還不是升級 OpenClaw 本體，反而是歷史遺留的飛書插件狀態(tài)。

原本想只要拉最新倉庫、執(zhí)行 pnpm install、重新啟動就夠了；但如果本機 ~/.openclaw 里已經(jīng)殘留了舊版飛書插件 feishu-openclaw-plugin，升級后就很容易出現(xiàn)插件 ID 不匹配、健康檢查異常、飛書鑒權(quán)報錯等問題。

這篇文章記錄一下我這次從舊環(huán)境升級到可用狀態(tài)的完整過程，給后面碰到類似問題的人一個可復(fù)用的參考。

一、環(huán)境背景

我的場景比較典型：

• 機器上以前已經(jīng)安裝過舊版 OpenClaw
• 歷史數(shù)據(jù)目錄在 ~/.openclaw
• 代碼倉庫已經(jīng)拉到最新
• 已經(jīng)執(zhí)行過 pnpm install
• 飛書側(cè)以前裝過舊版官方插件

升級前的直覺通常是：既然倉庫已經(jīng)更新，直接重新構(gòu)建、重啟就好。

但真實情況是：舊版飛書插件和新版官方插件不是簡單覆蓋關(guān)系，而是一次遷移關(guān)系。

二、問題現(xiàn)象

一開始我遇到的現(xiàn)象并不統(tǒng)一，但本質(zhì)都指向同一個問題：舊插件殘留。

典型表現(xiàn)包括：

• openclaw 可以啟動，但某些命令執(zhí)行失敗
• openclaw health 里 Feishu 不正常
• 提示類似 plugin id mismatch
• 網(wǎng)關(guān)啟動后飛書能力異常
• 舊的插件目錄和配置還殘留在 ~/.openclaw/extensions

核心問題是：舊插件 feishu-openclaw-plugin 還留在環(huán)境里，而新版安裝路徑已經(jīng)切到 openclaw-lark。

三、先升級 OpenClaw 本體

第一步仍然是把 OpenClaw 本體升級到最新，并確保當(dāng)前代碼能正常構(gòu)建。

我本地做的事情包括：

pnpm install
pnpm build

如果你是從源碼運行，這一步很重要，因為有些舊的 dist 構(gòu)建產(chǎn)物和新依賴版本不一致時，會出現(xiàn)看起來很奇怪的運行時錯誤。

構(gòu)建完成之后，建議先跑一遍修復(fù)命令，把 ~/.openclaw 里的歷史狀態(tài)整理一下：

openclaw doctor --repair --non-interactive

這一步的作用是先把基礎(chǔ)環(huán)境整理干凈，比如：

• 清理過期鎖文件
• 修補配置
• 修復(fù)部分狀態(tài)目錄問題
• 確認(rèn)網(wǎng)關(guān)服務(wù)狀態(tài)

四、真正的關(guān)鍵：用飛書官方安裝器做遷移

真正解決問題的關(guān)鍵步驟，是運行飛書官方插件安裝器，而不是只靠 OpenClaw 主程序本身。

根據(jù)飛書官方文檔，我最終執(zhí)行的是：

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

這條命令非常關(guān)鍵，因為它會主動檢查舊環(huán)境，必要時執(zhí)行遷移。

我本次實際執(zhí)行時，它輸出了非常關(guān)鍵的一段信息：

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

也就是說，安裝器明確識別出了舊版插件殘留，并自動執(zhí)行了卸載。

隨后它完成了幾件事：

• 卸載舊插件 feishu-openclaw-plugin
• 刪除舊插件對應(yīng)的配置項、安裝記錄、allowlist 條目和插件目錄
• 安裝新版官方插件 openclaw-lark
• 復(fù)用已有的飛書機器人配置
• 自動重啟網(wǎng)關(guān)服務(wù)

安裝成功后，終端里會看到類似這樣的結(jié)果：

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

五、遷移后的配置狀態(tài)

安裝完成后，我又執(zhí)行了一次：

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

這一步可以非常直觀地驗證當(dāng)前環(huán)境到底處于什么狀態(tài)。

遷移完成后，關(guān)鍵配置變成了下面這種結(jié)構(gòu)：

• plugins.allow 中包含 openclaw-lark
• plugins.entries.openclaw-lark.enabled = true
• 內(nèi)置 feishu 插件為 enabled = false
• 舊的 feishu-openclaw-plugin 已經(jīng)被清理掉

這點非常重要。

很多人看到“內(nèi)置 feishu 被禁用”會以為出問題了，但在這條官方遷移路徑里，這其實是正常結(jié)果。因為現(xiàn)在真正負(fù)責(zé)飛書能力的是新版官方插件 openclaw-lark，而不是歷史上的舊外部插件，也不是當(dāng)前倉庫內(nèi)置的社區(qū) feishu 插件路徑。

六、最終驗證：看 openclaw health

判斷這次升級是否真正完成，最直接的命令只有一個：

openclaw health

我最終看到的關(guān)鍵輸出是：

Feishu: ok

只要這一行是 ok，基本就說明下面幾件事同時成立：

• OpenClaw 本體已經(jīng)升級成功
• 網(wǎng)關(guān)服務(wù)已經(jīng)正常運行
• 飛書官方插件已完成遷移
• 飛書插件與當(dāng)前配置可以正常協(xié)同

如果這里依舊報錯，那問題才需要繼續(xù)往飛書權(quán)限、應(yīng)用配置、用戶授權(quán)方向排查。

七、我這次升級的最終結(jié)論

這次踩坑之后，我的結(jié)論很明確：

如果機器上以前安裝過舊版 OpenClaw，并且 ~/.openclaw 里殘留了舊版飛書插件，那么升級時不要只更新倉庫和依賴。正確做法是：先升級 OpenClaw 本體，再運行飛書官方安裝器完成官方插件遷移。

換句話說，這不是一次簡單的“版本升級”，而是一場“歷史插件遷移”。

如果你只做了下面這些動作：

git pull
pnpm install
pnpm build

然后就直接期待飛書恢復(fù)正常，往往是不夠的。

真正閉環(huán)的動作應(yīng)該是：

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 倉庫代碼并安裝依賴
• 重新構(gòu)建，確保本體可運行
• 運行 openclaw doctor --repair
• 使用飛書官方安裝器執(zhí)行插件遷移
• 用 openclaw health 驗證最終狀態(tài)

額外提醒兩點：

• 如果安裝器檢測到舊插件并自動遷移，不要手動再把舊插件重新啟用
• 如果你在公開場景貼過 gateway.auth.token，記得立即重新生成并重啟網(wǎng)關(guān)

可執(zhí)行：

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

九、結(jié)尾

這次升級里最容易誤判的一點，是把問題歸咎于“配置不對”或者“權(quán)限不全”，但實際根因是舊版飛書插件殘留帶來的遷移問題。

只要官方安裝器已經(jīng)完成舊插件卸載、新插件安裝，并且 openclaw health 明確顯示：

Feishu: ok

那這次升級才算真正完成。

如果你正好也卡在舊版 OpenClaw 升級飛書插件這件事上，希望這篇記錄能幫你少繞一點彎路。

飛書插件官方文檔： https://bytedance.larkoffice.com/docx/MFK7dDFLFoVlOGxWCv5cTXKmnMh

到此這篇關(guān)于升級 OpenClaw 到最新版 + 遷移飛書官方插件的踩坑記錄的文章就介紹到這了,更多相關(guān)OpenClaw飛書插件升級內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評論