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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点固定为 https://taotoken.net/api ，注意这个地址后面不加任何 UTM 参数，配置里写干净的这个就行。
你需要先拿到一个 API Key。进控制台创建：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 页面点新建，复制那串sk-开头的密钥。这个 Key 就是后面配置里的apiKey字段，别泄露，也别提交到 Git 仓库。
模型 ID 怎么选？如果你只是让 OpenClaw 做消息理解、意图分类这类轻量任务，选一个通用对话模型就够；如果涉及代码生成或复杂 Agent 编排，可以挑能力更强的。具体可用模型列表在文档里查：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。我实测下来，把模型 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，进去装缺失的 SDK：
cd /opt/openclaw npm install @larksuiteoapi/node-sdk --save-exact加--save-exact是为了锁定精确版本，避免下次npm install时自动升级到不兼容的新版。装完确认一下：
npm ls @larksuiteoapi/node-sdk正常应该输出类似└── @larksuiteoapi/node-sdk@x.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, model=claude-sonnet-4-5 [INFO] response received, tokens=42如果看到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 --omit=optional这种参数会把可选依赖排除掉，去掉它。另外确认 CI 的 Node 版本和本地一致，版本差异也会导致依赖解析行为不同。
排查时记住一个原则：先确认"包在不在"，再确认"路径对不对"，最后确认"端点通不通"。三步走完，九成问题都能定位。
6. 把配置固化下来：长期编码与 Agent 场景的接入建议
修完这一次，更重要的是别让它再犯。我的做法是把"启用渠道前先装对应依赖"写进团队的标准操作流程，具体落地成三件事。
第一件，维护一份渠道-依赖对照表，放在仓库根目录的CHANNELS.md里。每启用一个新渠道，就在表里加一行，标注依赖包名和安装命令。比如飞书对应@larksuiteoapi/node-sdk，Discord 对应它自己的 SDK。新人接手时照着表装，不用每次现场排查。
第二件，把依赖安装写进package.json的optionalDependencies或单独的安装脚本。这样npm install时会自动带上，减少遗漏。如果你担心包体积，可以用npm install --no-save在 CI 里临时装，但记得在流水线里显式声明。
第三件，如果你要长期跑编码类任务或 Agent 编排，建议用 Coding Plan 来管理模型调用配额和路由：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。它比单次 API 调用更适合高频场景，配置方式跟上面一样，把 Base URL 和 Key 填对就行。
对于 Claude Code 这类工具的接入，配置逻辑是相通的：Base URL 填https://taotoken.net/api，Key 填你的密钥，Model ID 按文档选。三件套齐了就能跑。如果你在找模型对话的调试入口，可以在这里试：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite ，先用对话确认模型可用，再往 OpenClaw 里配，能省不少排查时间。
最后给个实用技巧：在 OpenClaw 启动脚本里加一行依赖自检，启动前先跑npm ls @larksuiteoapi/node-sdk，缺失就自动装。这样即使换了环境，服务也能自己把依赖补齐，不用人工介入。脚本大概这样：
#!/bin/bash if ! npm ls @larksuiteoapi/node-sdk > /dev/null 2>&1; then echo "检测到飞书 SDK 缺失，正在安装..." npm install @larksuiteoapi/node-sdk --save-exact fi node lib/index.js把这段作为启动入口，以后不管本地还是 CI，都不会再被Cannot find module卡住。配置固化下来，重复排查的成本就归零了。
