OpenClaw 飞书配对、QQ 插件升级与全局依赖补全:踩坑记录与处理办法

摘要:本文记录在将 OpenClaw 与飞书、QQ 机器人渠道联调、升级过程中遇到的典型报错,说明其含义,并给出可复现的解决步骤。适用场景:自建 Gateway、yarn 全局安装 OpenClaw、同时启用 openclaw-lark 与 openclaw-qqbot 等扩展。


一、飞书私聊提示「OpenClaw: access not configured」

现象

在飞书中向机器人发私聊,收到类似回复:

text 复制代码
OpenClaw: access not configured.
ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Pairing code: XXXXXXXX
Ask the bot owner to approve with:
openclaw pairing approve feishu XXXXXXXX

含义

这不是 「OpenClaw 没配好」的系统故障提示,而是私信安全策略下的**配对(pairing)**流程文案:

  • 第一行来自 OpenClaw 的配对挑战模板,实际想表达的是:当前发送者尚未被授权私聊该机器人。
  • ou_... 为飞书用户的 Open ID。
  • Pairing code 是一次性配对码,需由机器人管理员在运行 Gateway 的环境用 CLI 批准。

处理办法(管理员)

在配置目录所在环境执行(将 CODE 换成实际配对码):

bash 复制代码
openclaw pairing approve feishu CODE

多飞书应用(多 account)时,可能需要指定账号,例如:

bash 复制代码
openclaw pairing approve feishu CODE --account <accountId>

查看待处理请求:

bash 复制代码
openclaw pairing list feishu

批准后,该用户通常会写入本地允许列表,同一机器人、同一环境下一舨无需再次配对(除非清理数据、换机或多实例存储不一致)。

延伸:只有我一个人用,不想每次配对

默认 channels.feishu.dmPolicy 常为 pairing,陌生人会反复走配对。若只有固定账号需要访问:

  1. 将 channels.feishu.dmPolicy 设为 allowlist。
  2. 在 channels.feishu 顶层 设置 allowFrom ,填入允许的飞书 Open ID(ou_...)。

这样所有合并了顶层配置的子账号(如 main / coding / docs 等多机器人)都会继承同一套私信白名单,避免「只写在某个 accounts.* 节点却对实际在用的账号不生效」的问题。群聊若使用 groupPolicy: "allowlist",也应把 groupAllowFrom 放在顶层或每个在用账号下,保证策略一致。

修改后需 openclaw gateway restart(或等价重启方式)使配置生效。

注意 :allowlist 下未列入的用户将无法私聊,适合个人或小团队;若需对租户内所有人开放,需改用文档中的 open 策略并按要求配置通配(安全风险更高)。


二、QQ 机器人插件:从旧版升级到 v1.6.7

现象

群内或日志提示有新版本(例如 v1.6.7,当前仍为 v1.6.1),并建议使用 /qqbot-upgrade 升级。

含义

/qqbot-upgrade 本质是触发在扩展目录中安装 @tencent-connect/openclaw-qqbot 的最新 npm 版本,而不是只改 OpenClaw 主程序版本号。

处理办法

在已安装的扩展目录执行(路径以本机 openclaw.json 里 gateway.plugins.installs.openclaw-qqbot.installPath 为准,常见为 ~/.openclaw/extensions/openclaw-qqbot):

bash 复制代码
cd ~/.openclaw/extensions/openclaw-qqbot
npm install @tencent-connect/openclaw-qqbot@latest

安装完成后:

  • 确认 node_modules/@tencent-connect/openclaw-qqbot/package.json 中 version 已为预期(如 1.6.7)。
  • 重启 Gateway :openclaw gateway restart。

版本号对齐

扩展根目录常有一份额外的 package.json(包装层),其 version 可能与依赖包不一致。为减少排查时的混淆,可将根目录 package.json 的 version 与已安装的 @tencent-connect/openclaw-qqbot 保持一致。

同时建议在 openclaw.json 的 gateway.plugins.installs.openclaw-qqbot 中更新 version、resolvedVersion、resolvedSpec、npm integrity 等元数据,便于日后用 openclaw 自带能力管理插件时记录准确。


三、全局 OpenClaw(yarn global)加载 QQ 插件失败:Cannot find module 'silk-wasm'

现象

日志类似:

text 复制代码
[plugins] qqbot failed to load from .../node_modules/openclaw/dist/extensions/qqbot/index.js:
Error: Cannot find module 'silk-wasm'
Require stack:
- .../openclaw/dist/outbound-xxxxx.js

原因

若 OpenClaw 通过 yarn global 安装在例如 ~/.config/yarn/global/node_modules/openclaw,主包的 dependencies 里可能未声明 silk-wasm,而打包后的 outbound 等模块会直接 import silk-wasm (用于 QQ 语音相关编解码)。Node 在解析模块时在该包的 node_modules 中找不到 silk-wasm,导致 qqbot 扩展加载失败。

(同类问题:日志中若出现 @aws-sdk/client-bedrock 缺失,多为内置 amazon-bedrock 扩展需要 AWS SDK,而全局安装同样未附带该依赖。)

处理办法

在全局 openclaw 包目录内补装依赖(路径按本机为准):

bash 复制代码
cd ~/.config/yarn/global/node_modules/openclaw
npm install silk-wasm mpg123-decoder --save

mpg123-decoder 在同一条音频处理链路中可能被动态引用,一并安装可降低后续再报缺模块的概率。

可用下列方式快速验证:

bash 复制代码
cd ~/.config/yarn/global/node_modules/openclaw
node -e "import('silk-wasm').then(() => console.log('silk-wasm ok'))"

然后再次 重启 Gateway。

维护提示

对 node_modules/openclaw 内 package.json 的手工增删依赖 ,在下次执行 yarn global upgrade openclaw 等整包覆盖升级 时可能被覆盖 ,若升级后问题复现,需在同一目录重新执行一次 npm install silk-wasm mpg123-decoder(或等待上游在主包中正式声明这些依赖)。


四、小结与建议

问题 核心原因 处理要点
飞书「access not configured」+ 配对码 私信 pairing 策略,发送者未批准 openclaw pairing approve feishu <CODE>;单人可改用顶层 allowlist + allowFrom
QQ 插件版本落后 npm 包未更新 在 extensions/openclaw-qqbot 执行 npm install @tencent-connect/openclaw-qqbot@latest 并重启 Gateway
silk-wasm 找不到 全局 OpenClaw 未安装该传递依赖 在全局 openclaw 目录 npm install silk-wasm mpg123-decoder
Bedrock 插件加载失败 缺少 @aws-sdk/client-bedrock 同上,在全局包目录安装对应模块(若实际启用该扩展)

实践建议:

  1. 变更配置或升级插件后固定动作 :重启 Gateway,并扫一眼 openclaw logs。
  2. 多飞书应用时,私信/群策略尽量在 channels.feishu 顶层 写清 allowFrom / groupAllowFrom,避免子账号继承不到。
  3. 全局安装 OpenClaw 的用户,升级主程序后若扩展突然缺模块,优先在该全局包目录 下 补装报错中的 npm 包,再考虑向项目提 issue 推动上游纳入依赖声明。

本文基于实际环境整理,OpenClaw 与插件版本迭代较快,具体 CLI 与配置键请以当前版本官方文档为准。

相关推荐
w3296362713 天前
飞书接单到月度结算:我用一个 DSH 插件跑通鞋类采购 WMS,附 22 项验收
pdf·node.js·飞书·后端开发·ai agent
宝哥聊编程15 天前
主流 Agent 平台对比:Coze、Dify、飞书、扣子、OpenClaw 落地实操手册
前端·人工智能·飞书
guoran_shini16 天前
Agent系统服务化封装和IM接入
飞书
mudtools19 天前
在飞书 SDK 上用 Microsoft Agent Framework 搭一个能干活的工作搭子
人工智能·ai·.net·飞书·agent
极致了20 天前
飞书插件、RPA、API三条路的真实分界线
飞书·rpa
玩泥巴的21 天前
在飞书 SDK 上用 Microsoft Agent Framework 搭一个能干活的工作搭子
ai·.net·飞书·agent
玩泥巴的22 天前
一份声明,多份产物:飞书 SDK 的 AI 工具面是怎么生成的
ai·.net·飞书·agent
OpenPortal认证计费系统24 天前
基于 飞书认证 通过 华为、H3C 结合 OpenPortal认证计费系统 实现 网络准入 飞书授权 实名认证
华为·飞书·h3c·portal认证·openportal
前进的李工24 天前
飞书企业知识库设计+后端高频八股
数据库·redis·后端·mysql·性能优化·飞书·rag