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/console，API 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.toml（Windows 下是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-qqbot@latest # 第二步：加 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/qqbot@latest… 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/api，api_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。这个不在报错信息里，但确实会影响安装成功率。
