1. OpenClaw 启动报 Cannot find module 的真实场景与排查思路OpenClaw 是一个支持多渠道接入的开源消息网关你可以把它理解成一个消息路由器它把飞书、企业微信、Slack、Discord 等不同平台的消息统一收进来再按你的配置分发出去。它的核心安装包做得很轻各个渠道的第三方 SDK 采用按需加载的方式只有你在配置文件里真正启用了某个渠道对应的依赖包才会被require()加载。这个设计本身没问题但坑就坑在——很多人配好飞书渠道、满心欢喜敲下启动命令结果迎面一个Error: Cannot find module larksuiteoapi/node-sdk服务直接起不来。这个报错适合谁看如果你正在本地开发环境调试 OpenClaw 的飞书渠道或者在 CI 流水线里跑集成测试时突然挂掉又或者从旧服务器迁移过来只拷了配置文件没拷node_modules那这篇就是给你写的。核心检索词就三个OpenClaw、Cannot find module、larksuiteoapi/node-sdk围绕它们把为什么报、怎么修、怎么验证、怎么防讲透。先看报错长什么样。典型输出是这样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) at Module._load (node:internal/modules/cjs/loader:901:27) at Module.require (node:internal/modules/cjs/loader:1119:19)注意Require stack这一行它告诉你是谁在找这个模块——这里是lib/channels/lark.js也就是飞书渠道的加载器。Node.js 的模块解析是运行时行为代码执行到require(larksuiteoapi/node-sdk)这一句时才会去node_modules目录里翻这个包翻不到就抛Cannot find module。所以这个错跟 OpenClaw 核心代码有没有 bug 无关纯粹是该装的包没装到位。触发链路可以这样梳理OpenClaw 启动 → 读取配置文件 → 发现channels.lark.enabled为 true → 运行时加载channels/lark.js→ 该文件内部require(larksuiteoapi/node-sdk)→ 检查node_modules下是否存在该包 → 不存在则报错。整条链路里唯一能出问题的就是最后一步的存在性检查。常见原因我归成四类。第一类是可选依赖压根没装OpenClaw 核心包不含渠道 SDK得单独npm install。第二类是升级或迁移后依赖丢失从旧版本升上来、或者换服务器时只拷了配置和代码node_modules没跟着走。第三类是多渠道只装了部分依赖你同时开了飞书和 Discord结果只记得装了一个。第四类是安装过程被网络打断npm install跑了一半失败但整体流程没明确报错留下一个残缺的node_modules。这四类的处理方式略有差别下面逐个给可复制的操作。排查时有个小技巧先确认是从来没装过还是装过但丢了。执行npm ls larksuiteoapi/node-sdk如果输出(empty)或UNMET DEPENDENCY说明没装如果输出路径但文件缺失说明装过但被删了。这一步能帮你少走弯路。2. TaoToken 前置准备把 Base URL 与 Key 配到位修完模块缺失只是第一步OpenClaw 的飞书渠道要真正跑起来还得有可用的模型服务端点。这里我用 TaoToken 来做统一接入它的好处是 Base URL 和 Key 一套配置就能覆盖多个模型省得每个渠道单独折腾。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点固定为 https://taotoken.net/api 注意这个地址后面不加任何 UTM 参数配置里写干净的这个就行。你需要先拿到一个 API Key。进控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面点新建复制那串sk-开头的密钥。这个 Key 就是后面配置里的apiKey字段别泄露也别提交到 Git 仓库。模型 ID 怎么选如果你只是让 OpenClaw 做消息理解、意图分类这类轻量任务选一个通用对话模型就够如果涉及代码生成或复杂 Agent 编排可以挑能力更强的。具体可用模型列表在文档里查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。我实测下来把模型 ID 写成完整名称比如claude-sonnet-4-5这类比写别名更稳避免解析歧义。这里要强调一个容易混的点larksuiteoapi/node-sdk是飞书渠道用来收发消息的 SDK跟模型服务是两码事。前者解决消息怎么进出飞书后者解决消息内容交给哪个模型处理。两个都得配缺一个都跑不通。很多人修完模块报错结果启动成功但渠道不工作就是 Base URL 或 Key 没填对。配置前建议先确认 Node.js 版本。OpenClaw 一般要求 Node 18 以上执行node -v看一眼。版本太低会导致某些依赖装不上间接引发模块找不到。如果版本不够先用 nvm 切一个 LTS 版本再继续。另外如果你在 CI 环境里跑记得把 API Key 通过环境变量注入而不是硬编码进配置文件。比如在 GitHub Actions 里用secrets.TAOTOKEN_API_KEY在配置里引用process.env.TAOTOKEN_API_KEY。这样既安全也方便不同环境切换。3. 可复制配置npm 依赖锁定与 Base URL 改写这一节是重头戏给你能直接抄的配置片段。先解决模块缺失再改 Base URL。第一步定位 OpenClaw 的实际安装目录。如果你是用npm install -g openclaw全局装的目录可能在/usr/local/lib/node_modules/openclaw或~/.nvm/versions/node/vXX/lib/node_modules/openclaw如果是克隆源码跑的就是你 clone 下来的那个目录。用which openclaw或npm root -g辅助定位。假设目录是/opt/openclaw进去装缺失的 SDKcd /opt/openclaw npm install larksuiteoapi/node-sdk --save-exact加--save-exact是为了锁定精确版本避免下次npm install时自动升级到不兼容的新版。装完确认一下npm ls larksuiteoapi/node-sdk正常应该输出类似└── larksuiteoapi/node-sdkx.y.z。如果还是UNMET说明装错目录了检查你是不是在全局包目录之外执行的。第二步改配置文件。OpenClaw 的配置通常是 JSON 或 TOML 格式路径一般在项目根目录的config.json或openclaw.config.toml。下面给一份 JSON 片段把飞书渠道和 TaoToken 端点都配进去{ channels: { lark: { enabled: true, appId: cli_xxxxxxxx, appSecret: your_lark_app_secret, verificationToken: your_verification_token } }, model: { baseUrl: https://taotoken.net/api, apiKey: sk-your-taotoken-key, modelId: claude-sonnet-4-5, timeout: 60000 } }注意baseUrl写的是https://taotoken.net/api不带任何查询参数。apiKey填你从控制台拿的那串。modelId按文档里的可用名称填。timeout给 60 秒飞书消息处理有时会慢太短容易超时。如果你用的是 TOML 格式等价写法是这样[channels.lark] enabled true appId cli_xxxxxxxx appSecret your_lark_app_secret verificationToken your_verification_token [model] baseUrl https://taotoken.net/api apiKey sk-your-taotoken-key modelId claude-sonnet-4-5 timeout 60000第三步如果你在 CI 里跑建议把依赖安装写进流水线脚本别依赖人工记忆。比如在package.json的postinstall里加一句或者单独写个setup.sh#!/bin/bash set -e npm ci npm install larksuiteoapi/node-sdk --save-exact echo 依赖安装完成npm ci会严格按照package-lock.json安装比npm install更可复现。装完再补飞书 SDK双保险。第四步Docker 场景。别等容器跑起来才发现缺包在 Dockerfile 构建阶段就装好FROM node:18-slim WORKDIR /app COPY package*.json ./ RUN npm ci npm install larksuiteoapi/node-sdk --save-exact COPY . . CMD [node, lib/index.js]这样每次重建镜像依赖都是完整的不会出现本地能跑、容器报错的割裂。配置改完重启服务openclaw restart或直接node lib/index.js。如果之前是Cannot find module现在应该能过模块加载这一关。接下来验证请求是否真的通。4. 验证请求与成功结果最小复现确认报错消失修完配置别急着庆祝得用最小动作验证两件事模块能加载、模型端点能通。先写一个最小复现脚本单独测模块加载// test-lark-sdk.js try { const sdk require(larksuiteoapi/node-sdk); console.log(模块加载成功导出字段, Object.keys(sdk).slice(0, 5)); } catch (err) { console.error(模块加载失败, err.message); process.exit(1); }在 OpenClaw 安装目录下执行node test-lark-sdk.js。成功的话会打印导出字段列表说明larksuiteoapi/node-sdk已经能被正常解析。这一步能排除装是装了但路径不对的情况。接着验证 TaoToken 端点。用一个最简单的 curl 请求测模型服务是否可达curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-taotoken-key \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}], max_tokens: 10 }正常返回是一段 JSON包含choices数组和模型回复内容。如果返回 401说明 Key 不对返回 404说明路径或模型 ID 写错连接超时检查网络和 Base URL 拼写。这一步过了说明模型端点没问题。最后做端到端验证启动 OpenClaw在飞书里给机器人发一条消息看服务日志有没有正常处理。成功日志大概长这样[INFO] lark channel loaded successfully [INFO] model request sent, modelclaude-sonnet-4-5 [INFO] response received, tokens42如果看到lark channel loaded successfully说明模块加载这关彻底过了。如果日志里出现Cannot find module又冒出来往下看排错章节。验证时有个细节如果你在 CI 里跑把上面两个验证脚本串进流水线任何一步失败就中断构建。这样能保证每次部署前依赖和端点都是好的不会把问题带到生产。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth修的过程中你大概率会撞上几个衍生报错这里逐个对照。401 Unauthorized。这个最常见通常是 API Key 填错或过期。检查配置文件里的apiKey是不是完整的sk-开头字符串有没有多余空格或换行。如果你用环境变量注入确认变量名拼写一致比如配置里写process.env.TAOTOKEN_API_KEY环境里就得真有这个变量。还有一种情况是 Key 被撤销了去控制台重新生成一个换上。local proxy failed。这个报错说明请求根本没发出去卡在本地网络层。先确认baseUrl写的是https://taotoken.net/api没有多余斜杠或路径。再检查本机 DNS 能不能解析这个域名nslookup taotoken.net试一下。如果公司网络有出口限制联系运维放行。注意别用任何非官方的网络工具直接走正常网络访问即可。reading choices 报错。典型信息是Cannot read properties of undefined (reading choices)意思是代码期望响应里有choices字段但实际拿到的是别的结构。原因通常是模型 ID 写错服务端返回了错误对象而不是正常响应。把modelId改成文档里确认可用的名称再测一次。也可能是baseUrl少了/v1或多了路径对照文档核对。OAuth 相关报错。如果你用的是 Claude Code 这类需要 OAuth 授权的工具报错可能提示 token 失效。这种情况去对应的授权页面重新走一遍流程拿到新 token 后更新配置。注意 OAuth token 和 API Key 是两套东西别混用。模块装了还报 Cannot find module。这是最气人的情况。先确认你npm install的目录和 OpenClaw 实际运行的目录是不是同一个。全局安装的包本地目录装是没用的。用node -e console.log(require.resolve(larksuiteoapi/node-sdk))看解析到哪个路径如果报错说明当前工作目录下确实没有。还有一种可能是NODE_PATH环境变量干扰了模块查找检查一下有没有设这个变量。CI 里本地能跑线上报错。多半是node_modules没被正确缓存或安装。检查流水线的安装步骤有没有跳过可选依赖npm ci --omitoptional这种参数会把可选依赖排除掉去掉它。另外确认 CI 的 Node 版本和本地一致版本差异也会导致依赖解析行为不同。排查时记住一个原则先确认包在不在再确认路径对不对最后确认端点通不通。三步走完九成问题都能定位。6. 把配置固化下来长期编码与 Agent 场景的接入建议修完这一次更重要的是别让它再犯。我的做法是把启用渠道前先装对应依赖写进团队的标准操作流程具体落地成三件事。第一件维护一份渠道-依赖对照表放在仓库根目录的CHANNELS.md里。每启用一个新渠道就在表里加一行标注依赖包名和安装命令。比如飞书对应larksuiteoapi/node-sdkDiscord 对应它自己的 SDK。新人接手时照着表装不用每次现场排查。第二件把依赖安装写进package.json的optionalDependencies或单独的安装脚本。这样npm install时会自动带上减少遗漏。如果你担心包体积可以用npm install --no-save在 CI 里临时装但记得在流水线里显式声明。第三件如果你要长期跑编码类任务或 Agent 编排建议用 Coding Plan 来管理模型调用配额和路由https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它比单次 API 调用更适合高频场景配置方式跟上面一样把 Base URL 和 Key 填对就行。对于 Claude Code 这类工具的接入配置逻辑是相通的Base URL 填https://taotoken.net/apiKey 填你的密钥Model ID 按文档选。三件套齐了就能跑。如果你在找模型对话的调试入口可以在这里试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 先用对话确认模型可用再往 OpenClaw 里配能省不少排查时间。最后给个实用技巧在 OpenClaw 启动脚本里加一行依赖自检启动前先跑npm ls larksuiteoapi/node-sdk缺失就自动装。这样即使换了环境服务也能自己把依赖补齐不用人工介入。脚本大概这样#!/bin/bash if ! npm ls larksuiteoapi/node-sdk /dev/null 21; then echo 检测到飞书 SDK 缺失正在安装... npm install larksuiteoapi/node-sdk --save-exact fi node lib/index.js把这段作为启动入口以后不管本地还是 CI都不会再被Cannot find module卡住。配置固化下来重复排查的成本就归零了。