【Bug已解决】OpenClaw 报错 Error: Cannot find module '@larksuiteoapi/node-sdk' 解决方案

1. 问题描述

给 OpenClaw 配置接入飞书（Lark）渠道后，启动服务时遇到模块加载失败：

Error: Cannot find module '@larksuiteoapi/node-sdk'
Require stack:
- /opt/openclaw/lib/channels/lark.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1075:15)

1.1 具体现象

1. 在配置文件里启用了 Lark/飞书渠道相关的配置项
2. 服务启动时直接报模块找不到，其他没有配置该渠道的功能正常
3. 用 npm list 查看，确实没有安装这个包
4. 有些人反馈"文档里没提到还要单独装这个包"，直接被这个报错卡住

这个问题的本质是OpenClaw 采用按需加载的可选依赖设计——不同的消息渠道（Lark、企业微信、Slack、Discord 等）各自依赖不同的第三方 SDK，只有当你在配置里真正启用某个渠道时，对应的依赖包才需要被安装，而这一点在很多场景下容易被文档遗漏说明或被用户忽略。

2. 原因分析

Node.js 的 require()/import 在运行时才会真正去解析并加载指定的模块，如果模块没有被安装到 node_modules 目录下，就会抛出 Cannot find module 错误。用一张流程图梳理触发链路：

OpenClaw 启动，读取配置文件
        ↓
检测到配置中启用了 Lark 渠道
        ↓
运行时加载 channels/lark.js 模块
        ↓
该模块内部 require('@larksuiteoapi/node-sdk')
        ↓
node_modules 目录下是否存在该包？
   ├─ 存在 → 正常加载，渠道功能可用
   └─ 不存在 → Cannot find module 错误

常见原因归纳：

原因分类	具体表现
可选依赖未安装	OpenClaw 核心安装包不包含所有渠道 SDK，需要按需单独安装
升级/迁移后依赖丢失	从旧版本升级、或者迁移到新服务器时，node_modules 没有完整迁移
多渠道配置但只装了部分依赖	同时启用了多个渠道，但只记得装了其中一个的 SDK
包管理器缓存不完整	网络问题导致某个依赖包下载中断，但整体安装流程没有明确报错

3. 解决方案

方案一：手动安装缺失的渠道 SDK（最直接）

cd /opt/openclaw   # 定位到 OpenClaw 的实际安装/部署目录
npm install @larksuiteoapi/node-sdk

# 安装完成后重启服务
openclaw restart

方案二：查阅官方文档确认每个渠道对应的依赖包

不同渠道对应不同的第三方 SDK，启用渠道前建议先确认清单，避免每次都是"报错了才知道要装什么"：

渠道	依赖包（示例，具体以官方文档为准）
飞书 / Lark	@larksuiteoapi/node-sdk
Discord	@buape/carbon 或对应的 Discord SDK
企业微信	官方企业微信 SDK 或对应适配包

方案三：用诊断命令批量检查所有已启用渠道的依赖完整性

# 部分版本的 OpenClaw 提供内置诊断命令
openclaw doctor

# 该命令会检查 Node.js 版本、已启用渠道对应的依赖是否完整等信息

如果诊断命令暂不支持某个渠道的依赖检查，可以自己写一个简单的批量校验脚本：

#!/bin/bash
channels=("@larksuiteoapi/node-sdk" "@buape/carbon")
for pkg in "${channels[@]}"; do
  if [ -d "node_modules/$pkg" ]; then
    echo "✅ $pkg 已安装"
  else
    echo "❌ $pkg 缺失，如已启用对应渠道请手动安装"
  fi
done

方案四：升级/迁移场景下重新完整安装依赖

如果是从旧环境迁移过来的部署，建议不要只拷贝配置文件，而是在新环境下完整重新执行一次依赖安装：

rm -rf node_modules
npm install
# 再根据实际启用的渠道补充安装对应的可选依赖

方案五：暂时禁用尚未准备好依赖的渠道，避免影响其他功能

如果暂时没有条件安装某个渠道依赖（比如网络访问受限），可以先在配置文件里临时关闭该渠道，确保核心服务和其他渠道功能不受影响，等依赖准备好后再重新启用：

{
  "channels": {
    "lark": {
      "enabled": false
    }
  }
}

4. 各方案对比总结

方案	适用场景	推荐指数
手动安装缺失 SDK	明确知道缺少哪个依赖包	⭐⭐⭐⭐⭐
查阅官方依赖清单	提前规划要启用哪些渠道	⭐⭐⭐⭐
诊断命令批量检查	启用了多个渠道，需要统一排查	⭐⭐⭐⭐
迁移场景重装依赖	从旧环境/旧服务器迁移过来的部署	⭐⭐⭐⭐
临时禁用渠道	暂时无法安装依赖，先保证核心功能可用	⭐⭐⭐

5. 常见问题 FAQ

5.1 为什么 OpenClaw 不把所有渠道依赖都打包进核心安装包？

这是常见的插件化架构设计权衡：把所有可能用到的第三方渠道 SDK 都作为强制依赖，会让核心安装包变得非常臃肿，而绝大多数用户往往只会用到其中一两个渠道，按需安装能让核心包保持轻量。

5.2 安装 SDK 之后还是报同样的错误，可能是什么原因？

检查安装位置是否正确——如果 OpenClaw 是通过全局安装的，而你在项目本地目录执行了 npm install，可能导致模块安装到了错误的 node_modules 目录下，需要确认实际运行时的模块查找路径。

5.3 Docker 部署场景下，应该在 Dockerfile 的哪个阶段安装这些可选依赖？

建议在构建镜像时就根据实际会启用的渠道，提前在 Dockerfile 里加入对应的 RUN npm install <渠道SDK> 步骤，而不是等容器运行起来之后才发现缺失，那样会导致每次容器重建都要重新安装。

5.4 团队里不同环境（开发/测试/生产）启用的渠道不一样，如何管理依赖？

建议维护一份清晰的文档，标注每个环境实际启用了哪些渠道、对应需要安装哪些依赖包，并在部署脚本/CI 流程里显式声明这些依赖安装步骤，而不是依赖"人工记忆"。

5.5 是否可以把所有渠道 SDK 都提前装好，以防将来要用？

可以，如果磁盘空间和构建时间不是主要顾虑，提前装好所有官方支持的渠道 SDK 确实能避免未来临时启用新渠道时再遇到这个报错，这是一种"空间换省心"的权衡选择。

5.6 这个报错和网络问题有关系吗？

间接有关。如果是因为网络问题导致某次 npm install 没有完整下载所有声明的依赖，也会表现为 Cannot find module，排查时可以先确认是否是"从来没装过"还是"装的过程中失败了"，两种情况的处理思路略有不同（前者手动补装即可，后者需要检查网络环境后重新安装）。

5.7 排查清单速查表

□ 1. 确认报错缺失的具体是哪个渠道 SDK 包名
□ 2. 确认该渠道是否在配置文件中被启用
□ 3. 手动安装对应的可选依赖包
□ 4. 用诊断命令或自查脚本批量检查所有已启用渠道的依赖完整性
□ 5. 迁移/升级场景确认是否需要完整重新安装依赖，而非只拷贝配置
□ 6. 暂时无法安装依赖时，先禁用对应渠道保证核心功能可用
□ 7. 团队协作场景维护清晰的渠道-依赖对照文档

6. 总结

Cannot find module '@larksuiteoapi/node-sdk' 报错的本质是OpenClaw 采用按需安装的可选依赖设计，而某个已启用的渠道对应的第三方 SDK 尚未安装，而不是核心程序本身有缺陷。核心处理思路：

1. 确认报错缺失的具体依赖包名，手动补装即可，这是最直接有效的方式；
2. 提前查阅官方文档，确认每个渠道对应的依赖清单，在启用渠道前就规划好安装步骤；
3. 迁移/升级场景务必重新完整安装依赖，不要只拷贝配置文件而忽略了 node_modules。

最佳实践建议：把"启用渠道前先确认并安装对应依赖"作为团队使用 OpenClaw 的标准操作流程写进文档，减少每次启用新渠道都要现场排查报错的重复成本。