OpenClaw 飞书插件加载失败？一次 Docker 容器内的模块路径排查实录

杭州留得发
20 阅读4分钟

OpenClaw 飞书插件加载失败？一次 Docker 容器内的模块路径排查实录

当你的 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 的插件加载机制

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/feishuroot-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 版本中存在这个路径问题。新版本可能已修复，但如果你和我一样卡在这个版本，上面的方法可以立即解决。

TL;DR 快速修复

如果你遇到 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 国际版（larksuite.com）WebSocket 模式下的实际排查过程。如果你也在用 OpenClaw 接飞书/Lark，希望这篇能帮你少走弯路。

avatar
文章
阅读
粉丝