OpenClaw 飞书插件升级踩坑复盘

背景

2026-03-16，尝试从飞书客户端触发 OpenClaw 飞书插件升级，目标是将官方插件 @larksuiteoapi/feishu-openclaw-plugin 从 v2026.2.28.4 升级至最新版本。

问题链

1. 插件安装到错误目录

升级过程将新插件安装到了 OpenClaw 的 npm 包目录内（~/.nvm/versions/node/v22.17.1/lib/lib/node_modules/openclaw/extensions/feishu/），而非正确的用户扩展目录（~/.openclaw/extensions/）。且安装的是社区版 @openclaw/feishu（@m1heng 维护），而非飞书官方版 @larksuiteoapi/feishu-openclaw-plugin。

2. 工作目录失效导致所有命令报错

由于当前 shell 的工作目录恰好在 openclaw 包内部（node_modules/openclaw/），更新过程中目录被重建，导致 shell 缓存的 cwd 失效。所有命令（pip、openclaw update、openclaw tui）均报 ENOENT: no such file or directory, uv_cwd 错误。

解决：cd ~ 切换到有效目录。

3. 插件 ID Mismatch 导致飞书 Channel 不可用

OpenClaw 2026.3.13 新增了插件 ID 一致性校验。官方插件的 openclaw.plugin.json 声明 id: "feishu-openclaw-plugin"，但 index.js 导出的是 id: "feishu"，两者不匹配。错误日志：

[plugins] plugin id mismatch (config uses "feishu-openclaw-plugin", export uses "feishu")
[tools] message failed: Unknown channel: feishu

飞书 Channel 因此未注册，所有消息无响应。

4. 误执行 openclaw reset 险些丢失全部配置

排查过程中尝试 openclaw restart（该命令不存在），终端提示 Did you mean reset?，误执行了 openclaw reset，删除了 openclaw.json、credentials 和 sessions。

抢救：依靠自动备份文件 openclaw.json.bak 恢复配置：

cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

5. 社区版与官方版配置键名不兼容

一度切换到社区版内置插件 @openclaw/feishu，发现其 config schema 使用 .strict() 校验，不支持官方版的 footer、threadSession 等配置键，导致流式卡片、时间状态等功能不可用。社区版对应的键名为 renderMode、replyInThread。

6. 删除旧插件后配置引用残留

手动 rm -rf 删除插件目录后，openclaw.json 中 plugins.allow、plugins.entries、plugins.installs 仍引用 feishu-openclaw-plugin，导致配置校验失败，openclaw plugins install 无法执行。

解决：手动清理配置中的过期引用后，才能重新安装。

7. 新版官方插件仍存在 ID Mismatch Bug

通过 openclaw plugins install @larksuiteoapi/feishu-openclaw-plugin 安装最新官方版 v2026.3.8 后，发现同样存在 id: "feishu" 与 "feishu-openclaw-plugin" 不匹配的问题。

解决：手动修改 index.js 中的导出 ID：

sed -i '''s/id: "feishu",/id: "feishu-openclaw-plugin",/' ~/.openclaw/extensions/feishu-openclaw-plugin/index.js

8. 流式卡片模式需额外配置 replyMode

即使 streaming: true 已设置，还需将 replyMode 设为 "streaming" 才能启用流式卡片回复：

openclaw config set channels.feishu.replyMode streaming

最终配置

{
"channels":{
"feishu":{
"appId":"cli_xxx",
"appSecret":"xxx",
"allowFrom":["ou_xxx"],
"historyLimit":30,
"streaming":true,
"replyMode":"streaming",
"footer":{"elapsed":true,"status":true},
"threadSession":true
}
}
}

教训与建议

1. 1. 升级前备份：cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.manual-bak，openclaw 的自动 .bak 文件救了这次。
2. 2. 区分社区版与官方版：@openclaw/feishu（社区）与 @larksuiteoapi/feishu-openclaw-plugin（官方）功能和配置不同，不可混用。
3. 3. 官方插件 ID Bug：已确认 v2026.3.8 仍存在此问题，建议向 larksuite/openclaw-lark 提交 Issue。
4. 4. 慎用 openclaw reset：它会删除配置、凭证和会话，不可逆。OpenClaw 没有 restart 命令，重启网关应使用 openclaw gateway restart。
5. 5. 不要在包目录内工作：避免将 shell 工作目录设置在 node_modules 内部，更新包时会导致目录失效。