OpenClaw飞书插件加载失败的问题排查与解决

目录

• 症状：单向失聪
• 第一步：看日志
• 第二步：理解 OpenClaw 的插件加载机制
• 第三步：修了一个坑，又踩一个
• 第四步：跳出框架，换个思路
• 复盘：为什么会这样？
• 快速修复
• 排查工具速查

当你的 AI 助手突然"聋了"——能发消息却收不到回复，问题可能藏在一个你根本不会去看的 .ts 文件里。

部署 OpenClaw + Lark（飞书国际版）后，一切看起来正常——WebSocket 模式配置好了，openclaw.json 里飞书配置齐全，容器也跑起来了。

但诡异的事情发生了：

• 通过 Lark API 主动发消息给用户 → 正常
• 用户在飞书上回复 → 石沉大海，Gateway 完全无反应

更离谱的是，容器首次启动后的前 3 分钟能收到消息，之后就彻底断了，重启也没用。

很多人遇到问题会先去翻文档、搜 Issue。但最快的路永远是：看日志。

openclaw channels logs

输出一行关键报错：

feishu failed to load from /app/extensions/feishu/index.ts: 
Error: Cannot find module '../../src/plugin-sdk/feishu.js'

飞书插件压根没加载成功。前 3 分钟能收消息？那大概是 WebSocket 连接建立的短暂窗口，插件崩溃后连接自然断开，且不会重连。

OpenClaw 的插件系统有两条路径：

路径	说明
Bundled（打包版）	编译进 /app/dist/ 的 JS chunks，开箱即用
External（外部加载）	通过 plugins.load.paths 指定源码目录，运行时用 jiti 转译

我的配置里有这么一段：

{
  "plugins": {
    "load": {
      "paths": ["/app/extensions/feishu"]
    }
  }
}

这就把 Gateway 指向了 源码目录 /app/extensions/feishu/，而不是已编译好的 bundled 版本。

源码目录里有个 runtime-api.ts，它负责重新导出插件 SDK：

// Docker 镜像 2026.3.14 中的内容
export * from "../../src/plugin-sdk/feishu.js";

问题来了：Docker 镜像里 根本没有 /app/src/ 目录——那是开发环境才有的路径。

GitHub 上最新代码已经改成了：

export * from "openclaw/plugin-sdk/feishu";

看起来合理，改上去试试？

Error: Cannot find module '/app/dist/plugin-sdk/root-alias.cjs/feishu'

Node.js 的 CJS require 把 openclaw/plugin-sdk/feishu 解析到了 root-alias.cjs/feishu——它把一个 文件 当成了 目录。 这是 OpenClaw 内部用 jiti 做模块别名时的一个边界情况。

好，那我直接用绝对相对路径：

export * from "../../node_modules/openclaw/dist/plugin-sdk/feishu.js";

这次模块找到了，但：

TypeError: (0 , _runtimeApi.buildChannelConfigSchema) is not a function

npm 包里的 feishu.js 导出了 48 个函数，但偏偏没有 buildChannelConfigSchema。这个函数在打包时被分到了另一个 chunk（config-schema-DjM6jQY2.js）。npm 包的模块拆分和 bundled 版本的 chunk 拆分不一致。

三条路全堵死了：

尝试	结果
../../src/plugin-sdk/feishu.js	路径不存在（Docker 没有 src/）
openclaw/plugin-sdk/feishu	root-alias.cjs 子路径解析 bug
直接指向 node_modules	导出不完整，缺关键函数

既然源码加载走不通，为什么不直接用 已经打包好的版本？

一查，/app/dist/extensions/feishu/ 目录赫然在目：

/app/dist/extensions/feishu/
├── index.js          ← 完整编译好的插件入口
├── setup-entry.js
├── package.json
├── openclaw.plugin.json
├── node_modules/
└── skills/

这才是 Gateway 应该加载的版本。它的 index.js 直接 import 同级的 bundled chunks，所有依赖关系在编译时已经解决了。

修复只需要改一行配置：

{
  "plugins": {
    "load": {
      "paths": ["/app/dist/extensions/feishu"]
    }
  }
}

重启，收工：

feishu_doc: Registered feishu_doc, feishu_app_scopes
feishu_chat: Registered feishu_chat tool
feishu_wiki: Registered feishu_wiki tool
feishu_drive: Registered feishu_drive tool
feishu_bitable: Registered bitable tools
Feishu default: enabled, configured, running ✅

这个问题的根因是开发态和生产态的路径差异：

• 开发环境： 有 /app/src/，jiti 能转译 TypeScript，源码加载没问题
• Docker 镜像： 只有 /app/dist/，源码路径失效，但配置仍然指向源码目录

飞书插件作为社区维护的扩展（@openclaw/feishu），在 2026.3.14 版本中存在这个路径问题。新版本可能已修复，但如果你和我一样卡在这个版本，上面的方法可以立即解决。

如果你遇到 Cannot find module '../../src/plugin-sdk/feishu.js'：

方案一（推荐）：改 openclaw.json 插件路径

{
  "plugins": {
    "load": {
      "paths": ["/app/dist/extensions/feishu"]
    }
  }
}

方案二： 升级 Docker 镜像

docker compose pull && docker compose up -d

命令	用途
openclaw channels status	查看插件加载状态
openclaw channels logs	查看频道日志（含报错）
openclaw channels status –probe	深度探测连接状态

本文记录的是 OpenClaw 2026.3.14 Docker 部署 + Lark 国际版WebSocket 模式下的实际排查过程。如果你也在用 OpenClaw 接飞书/Lark，希望这篇能帮你少走弯路。

到此这篇关于OpenClaw飞书插件加载失败的问题排查与解决的文章就介绍到这了,更多相关OpenClaw飞书插件加载失败内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！