1. openclaw2026.3.13 龙虾版装 QQ 插件我踩过的那些坑openclaw 2026.3.13 龙虾版社区里也有人叫它“龙虾版”在插件体系上做了一次比较大的调整plugins install和channels add这两条命令的配合方式跟老版本不太一样。如果你已经装好了 openclaw现在想接入 QQ 通道让机器人能在 QQ 群里收发消息那这篇就是写给你的。核心要装的是tencent-connect/openclaw-qqbot这个插件装完之后用channels add把 qqbot 通道挂上去中间会遇到配置校验失败、通道名不识别、临时目录解压报错、依赖安装失败、appid/secret 校验不通过这几类问题。我前后折腾了几天把每一步的报错和对应解法都记下来了下面按顺序给你捋一遍能直接复制的地方我都标了命令。先说清楚适用人群你已经有一个能跑起来的 openclaw 实例命令行能正常执行openclaw --version现在只差 QQ 通道这一步。如果你连 openclaw 都还没装那得先把主程序跑通再来看这篇。另外提醒一句网上流传的一些老命令比如直接改 config 文件、手动建 qq-bot.py在龙虾版上基本都会翻车别信按下面的流程走。2. 装 QQ 插件前先把 TaoToken 的 Key 和通道概念理清openclaw 本身是个调度框架它自己不产生模型能力得靠后端模型服务来驱动对话。我这边用的是 TaoToken 做模型接入它的 API 地址是https://taotoken.net/api控制台在https://taotoken.net/consoleAPI Keys 管理页在https://taotoken.net/api-keys。你需要在控制台里建一个 Key后面配到 openclaw 的模型配置里QQ 通道收到消息后才有模型可以调用。这里有个概念要分清plugins install装的是“能力插件”比如 qqbot 这个插件负责跟 QQ 开放平台通信channels add配的是“通道实例”它把插件和具体的 appid/appkey 绑定起来生成一个可用的通道。两者是分开的插件没装好channels add就会报Unknown channel: qqbot插件装好了但 token 填错通道能加上但发消息会返回invalid appid or secret。理解这个分层后面排错会快很多。如果你后面要长期跑编码类或 Agent 类的任务可以顺带看下 Coding Plan 页面https://taotoken.net/coding-plan它跟普通对话的计费方式不太一样。不过装 QQ 插件这一步用普通 API Key 就够了先把通道跑通再说。3. 可复制的 config.toml 骨架与两条核心命令先把配置文件骨架放出来你照着改。openclaw 龙虾版的配置一般在~/.openclaw/config.tomlWindows 下是C:\Users\你的用户名\.openclaw\config.toml。注意不要一上来就手改这个文件去“手动加通道”龙虾版有配置校验手改格式不对会直接报Config invalid; doctor will run with best-effort config.然后整个配置被降级处理反而更难排查。正确做法是先用命令装插件、加通道让程序自己写配置你只在必要时微调。# ~/.openclaw/config.toml 骨架龙虾版 2026.3.13 [model] provider taotoken api_base https://taotoken.net/api api_key 你的_TaoToken_Key [plugins] # 插件由 plugins install 自动登记这里一般不用手写 enabled [qqbot] [channels.qqbot] # 这一节由 channels add 生成token 格式是 appid:appkey token 你的appid:你的appkey两条核心命令按顺序执行# 第一步装 qqbot 插件认准 tencent-connect 这个 scope openclaw plugins install tencent-connect/openclaw-qqbotlatest # 第二步加 qqbot 通道token 用冒号拼接 appid 和 appkey openclaw channels add --channel qqbot --token 你的appid:你的appkey装插件那步如果卡在下载或解压先别急着换命令往下看第 5 节的临时目录问题。加通道那步如果报Unknown channel: qqbot说明插件没装成功回到第一步重装别去手改配置。4. 逐步验证从插件加载到通道生效装完不等于生效得一步步验证。我按顺序给你四个检查动作每步都有预期输出。第一步确认插件已登记openclaw plugins list预期能在列表里看到tencent-connect/openclaw-qqbot版本号是 latest 对应的那个。如果列表里没有说明 install 那步实际失败了哪怕命令行没报红。第二步确认通道已添加openclaw channels list预期能看到一个qqbot通道状态是enabled或active。如果这里报Unknown channel: qqbot就是插件层的问题不是通道参数的问题。第三步跑一次配置校验openclaw doctor预期输出里没有Config invalid字样。如果出现Config invalid; doctor will run with best-effort config.说明 config.toml 里有格式错误多半是你手改过。把[channels.qqbot]那节删掉重新用channels add生成。第四步实际发一条消息测试。在 QQ 里给机器人发个“你好”然后看 openclaw 日志openclaw logs --follow预期能看到[qqbot-api:xxx] Body: {code:0,...}这样的成功响应。如果返回{code:100016,message:invalid appid or secret}就是 token 填错了重点检查 appkey 有没有少字符。5. 本篇常见报错排查从 EISDIR 到 invalid appid这一节是重点我把遇到的报错按出现顺序列出来每个都给原因和解法。报错一Config invalid; doctor will run with best-effort config.这个几乎都是手改 config.toml 改出来的。网上有些教程让你直接往配置里加[channels.qqbot]节但龙虾版对缩进和字段名校验很严少个引号就报这个。解法把手工加的那节删掉用openclaw channels add重新生成。如果已经改乱了直接备份后删掉 config.toml重新跑一遍初始化。报错二Unknown channel: qqbot执行channels add时出现意思是插件没装成功程序不认识 qqbot 这个通道类型。解法先openclaw plugins list确认插件在不在不在就重装。注意插件名必须是tencent-connect/openclaw-qqbot网上有些写成sliverp/qqbot的是旧包龙虾版不认。报错三failed to extract archive: Error: EISDIR: illegal operation on a directory完整报错类似Downloading sliverp/qqbotlatest… Extracting Y:\TEMP\openclaw-npm-pack-06BV6I\sliverp-qqbot-1.6.1.tgz… failed to extract archive: Error: EISDIR: illegal operation on a directory, realpath Y:\TEMP\openclaw-plugin-mcmYDA\extract这个是我把 TEMP 指到了内存虚拟盘Y 盘导致的解压时对目录做 realpath 操作虚拟盘不支持。解法把临时目录改到真实磁盘。Windows 下在 PowerShell 里执行$env:TEMP C:\Temp $env:TMP C:\Temp然后在同一个终端窗口里重新跑plugins install。注意这个环境变量只对当前窗口生效换个窗口就没了所以装的时候别关终端。Linux/macOS 下对应改TMPDIR就行。报错四Installing plugin dependencies… npm install failed插件本体装上了但它依赖的 npm 包没装上。常见原因是网络或 npm 源问题。解法先确认 npm 能正常用然后手动进插件目录补装cd ~/.openclaw/extensions/qqbot npm installWindows 下路径是C:\Users\你的用户名\.openclaw\extensions\qqbot。如果 npm install 还是失败检查下 npm 源换成可用的镜像再试。报错五File C:\openclaw\scripts\qq-adapter\qq-bot.py, line 135, in module input(按回车键退出...)这个报错是网上教程让你手动建qq-bot.py脚本导致的那个脚本是旧方案的残留龙虾版根本不需要。解法把手工建的qq-bot.py删掉别去动scripts目录用官方插件方案。报错六{code:100016,message:invalid appid or secret}通道加上了但发消息时 QQ 开放平台返回这个。原因就一个token 里的 appid 或 appkey 填错了。我那次是 appkey 少粘贴了一个字符。解法去 QQ 开放平台后台重新复制 appid 和 appkey注意 appkey 通常比较长复制时别漏字符。然后重新加通道openclaw channels remove --channel qqbot openclaw channels add --channel qqbot --token 正确的appid:正确的appkey改完再发消息测试日志里看到code:0就通了。6. 通道跑通之后模型侧怎么接QQ 通道通了只是第一步机器人回复的内容得由模型生成。回到第 2 节说的 TaoToken 配置确认config.toml里[model]那节的api_base是https://taotoken.net/apiapi_key是你从https://taotoken.net/api-keys建的 Key。如果回复是空的或者报模型错误先去模型对话页https://taotoken.net/chat单独测一下 Key 能不能用排除是 Key 的问题还是通道的问题。调试阶段建议把日志级别调高openclaw logs --follow --level debug能看到模型请求和 QQ 回调的完整链路。等你确认通道和模型都通了再考虑长期跑编码或 Agent 任务那时候可以看下 Coding Planhttps://taotoken.net/coding-plan它的额度模型跟普通对话不一样适合高频调用场景。最后说个我踩过的坑装插件时如果终端里同时开着别的 openclaw 进程可能会出现文件占用导致解压失败。装之前先openclaw stop把服务停了装完再openclaw start。这个不在报错信息里但确实会影响安装成功率。