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:trueappId:"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:trueaccounts:-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:trueappId:$env: QQ_APP_ID appSecret:$secret: qq-app-secret 与其他渠道的对比
| 渠道 | 富媒体 | STT/TTS | 多账号 | 热升级 | 引用上下文 |
|---|---|---|---|---|---|
| QQ Bot | ✅ 全部 | ✅ STT+TTS | ✅ | ✅ | ✅ |
| 钉钉 | ✅ 图片/文件 | ❌ | ❌ | ❌ | ❌ |
| Slack | ✅ 全部 | ❌ | ❌ | ❌ | ❌ |
| 飞书 | ✅ 全部 | ❌ | ❌ | ❌ | ❌ |
| Telegram | ✅ 全部 | ✅ TTS | ❌ | ❌ | ❌ |
适用场景
- 技术社区运营：QQ 群是国内技术交流的重要场所，接入 AI 助手可以自动回答常见问题
- 个人助手：用自己的 AI 助手对接 QQ，随时随地提问
- 群管理：自动处理入群审核、常见问题回复
- 富媒体场景：需要处理图片、语音、文件的复杂对话场景
注意事项
- 插件本身只是消息通道：图片理解、语音识别等能力取决于你配置的 AI 模型，不是插件自带的功能
- 定时提醒可能被拦截：如果提醒没有送达，常见原因是 QQ 侧拦截了机器人的主动消息
- 引用消息索引持久化：存储在
~/.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/ |
技术没有捷径，但有方向
