OpenClaw 接入 QQ Bot 完整指南:让你的 AI 助手入驻 QQ

OpenClaw 接入 QQ Bot 完整指南：让你的 AI 助手入驻 QQ

TL;DR: OpenClaw 2026.3.31 正式支持 QQ Bot，可以接入 QQ 私聊、群聊，支持图片、语音、视频、文件等富媒体消息，还支持语音识别、日程提醒、Markdown 格式化等功能。

背景

QQ 是国内最主流的即时通讯工具之一，拥有大量技术社区用户。在此之前，OpenClaw 已经支持了钉钉、Slack、Telegram、飞书等渠道，这次更新终于把 QQ 也纳入了版图。

这次 QQ Bot 支持是由腾讯官方团队贡献的（@sliverp），直接对接 QQ 官方 Bot API，不是第三方桥接，稳定性有保障。

功能特性一览

功能	说明
🔒 多场景支持	C2C 私聊、群 @消息
🖼️ 富媒体	支持收发图片、语音、视频、文件
🎙️ 语音识别（STT）	语音消息自动转文字，AI 像处理文字一样处理语音
🔥 一键热升级	在私聊窗口发 `/bot-upgrade` 即可升级，无需登录服务器
⏰ 定时推送	通过 OpenClaw cron 定时主动发消息
🔗 URL 直链	私聊支持直接 URL 发送，无限制
⌨️ Typing 指示器	对方能看到「Bot 正在输入...」状态
📝 Markdown 格式	支持完整的 Markdown 渲染
💬 引用消息上下文	能识别 QQ 的 REFIDX_* 引用并注入引用内容到 AI 上下文
📦 大文件支持	最大支持 100MB 文件自动分片上传

安装前提

1. 创建 QQ 机器人

前往 QQ 开放平台创建应用，获取：

• App ID
• App Secret

2. 安装插件

openclaw plugins install @sliverp/qqbot

3. 配置

在 openclaw.json 中添加：

channels:  qq:    enabled: true    appId: "YOUR_APP_ID"    appSecret: "YOUR_APP_SECRET"    # 多账号支持    accounts:      - appId: "YOUR_APP_ID_1"        appSecret: "YOUR_APP_SECRET_1"      - appId: "YOUR_APP_ID_2"        appSecret: "YOUR_APP_SECRET_2"

核心功能详解

1. 富媒体消息

发送图片：直接让 AI 返回图片路径或 URL，插件自动转发到 QQ。

支持格式：jpg/png/gif/webp/bmp

发送语音（TTS）：AI 可以直接回复语音消息，插件自动转换。

支持格式：mp3/wav/silk/ogg，无需 ffmpeg

文件理解：发送 TXT、文档、表格等文件给 Bot，AI 自动识别内容并回复。

上传《战争与和平》txt → AI 自动总结第一章内容

2. 语音识别（STT）

配置 STT 后，语音消息会自动转成文字再交给 AI 处理。用户发送语音就像发送文字一样自然。

用户：(发送语音) "深圳明天天气怎么样？"Bot：明天（3月7日 周六）深圳天气预报 🌤️...

3. 引用消息上下文

QQ 的引用消息只携带 REFIDX_* 索引，不包含原文。插件现在会自动从本地持久化存储中查找引用原文，并注入到 AI 输入中，让 AI 理解「你在回复哪条消息」。

引用存储路径：~/.openclaw/qqbot/data/ref-index.jsonl（重启 Gateway 后仍然保留）

4. 一键热升级

在私聊窗口发送：

/bot-upgrade

插件会自动检测并升级，无需登录服务器，适合没有 SSH 权限的用户。

5. 日程提醒

用户：提醒我 5 分钟后吃饭Bot：确认日程 → 到点后主动发语音+文字提醒

依赖 OpenClaw 的 cron 调度和主动消息推送能力。

多账号支持

QQ Bot 支持多账号配置：

channels:  qq:    enabled: true    accounts:      - appId: "APP_ID_1"        appSecret: "APP_SECRET_1"        # 可选：为不同账号设置不同前缀        name: "Bot1"      - appId: "APP_ID_2"        appSecret: "APP_SECRET_2"        name: "Bot2"

SecretRef 凭证管理

生产环境建议使用 SecretRef 而非明文配置：

channels:  qq:    enabled: true    appId:      $env: QQ_APP_ID    appSecret:      $secret: qq-app-secret

与其他渠道的对比

渠道	富媒体	STT/TTS	多账号	热升级	引用上下文
QQ Bot	✅ 全部	✅ STT+TTS	✅	✅	✅
钉钉	✅ 图片/文件	❌	❌	❌	❌
Slack	✅ 全部	❌	❌	❌	❌
飞书	✅ 全部	❌	❌	❌	❌
Telegram	✅ 全部	✅ TTS	❌	❌	❌

适用场景

1. 技术社区运营：QQ 群是国内技术交流的重要场所，接入 AI 助手可以自动回答常见问题
2. 个人助手：用自己的 AI 助手对接 QQ，随时随地提问
3. 群管理：自动处理入群审核、常见问题回复
4. 富媒体场景：需要处理图片、语音、文件的复杂对话场景

注意事项

1. 插件本身只是消息通道：图片理解、语音识别等能力取决于你配置的 AI 模型，不是插件自带的功能
2. 定时提醒可能被拦截：如果提醒没有送达，常见原因是 QQ 侧拦截了机器人的主动消息
3. 引用消息索引持久化：存储在 ~/.openclaw/qqbot/data/ref-index.jsonl，定期清理可节省空间

下一步

• 📖 官方文档：QQ 开放平台
• 🔧 插件源码：GitHub - tencent-connect/openclaw-qqbot
• 📦 npm 包：@sliverp/qqbot

项目	内容
作者	胡小纯
发布日期	2026-03-24
联系微信	hu--xiaochun
个人主页	https://胡小纯.cn
备用主页	https://xn--yets91feqb.cn/

技术没有捷径，但有方向