# QQ Bot — OpenClaw 渠道插件
**让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
### 🚀 当前版本： `v1.6.2`
[](./LICENSE)
[](https://bot.q.qq.com/wiki/)
[](https://github.com/tencent-connect/openclaw-qqbot)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
扫描二维码加入群聊，一起交流
### 🎙️ 语音消息（STT）
配置 STT 后，插件会自动将语音转录为文字再交给 AI 处理。整个过程对用户完全透明——发语音就像发文字一样自然，AI 听得懂你在说什么。
> **你**：*（发送一段语音）*"明天深圳天气怎么样"
>
> **QQBot**：明天（3月7日 周六）深圳的天气预报 🌤️ ...
### 📄 文件理解
用户发文件给 AI，AI 同样能接住。不管是一本小说还是一份报告，AI 会自动识别文件内容并给出智能回复。
> **你**：*（发送《战争与和平》TXT 文件）*
>
> **QQBot**：收到！你上传了列夫·托尔斯泰的《战争与和平》中文版文本。从内容来看，这是第一章的开头……你想让我做什么？
### 🖼️ 图片理解
如果主模型支持视觉（如腾讯混元 `hunyuan-vision`），用户发图片 AI 也能看懂。这是多模态模型的通用能力，非插件专属功能。
> **你**：*（发送一张图片）*
>
> **QQBot**：哈哈，好可爱！这是QQ企鹅穿上小龙虾套装吗？🦞🐧 ...
### 🎨 图片发送
> **你**：画一只猫咪
>
> **QQBot**：画好啦！一只可爱的简笔小猫咪🐱🎨
AI 可直接发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
### 🔊 语音发送
> **你**：给我讲一个笑话
>
> **QQBot**：*（发送一条语音消息）*
AI 可直接发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
### ⏰ 定时提醒（主动消息）
> **你**：5分钟后提醒我吃饭
>
> **QQBot**：先确认已创建提醒，到点后再主动推送语音 + 文本提醒
该能力依赖 OpenClaw cron 调度与主动消息能力。若未收到提醒，常见原因是 QQ 侧拦截了机器人主动消息。
### 📎 文件发送
> **你**：战争与和平的第一章截取一下发文件给我
>
> **QQBot**：*（发送 .txt 文件）*
AI 可直接发送文件。任意格式，最大 20MB。
### 🎬 视频发送
> **你**：发一个演示视频给我
>
> **QQBot**：*（发送视频）*
AI 可直接发送视频，支持本地文件和公网 URL。
> **底层细节：** 上传去重缓存、有序队列发送、音频格式多层降级。
### 🛠️ 斜杠指令
插件内置一组斜杠指令，在消息进入 AI 队列前拦截处理，即时响应，用于诊断和管理。
#### `/bot-ping` — 延迟测试
> **你**：`/bot-ping`
>
> **QQBot**：✅ pong！⏱ 延迟: 602ms（网络传输: 602ms，插件处理: 0ms）
测量从 QQ 服务器推送到插件响应的端到端延迟，细分网络传输和插件处理两段耗时。
#### `/bot-version` — 版本信息
> **你**：`/bot-version`
>
> **QQBot**：🦞框架版本：OpenClaw 2026.3.13 (61d171a) / 🤖QQBot 插件版本：v1.6.2 / 🌟官方 GitHub 仓库
一目了然查看框架版本、插件版本，并可直接跳转官方仓库。
#### `/bot-help` — 指令列表
> **你**：`/bot-help`
>
> **QQBot**：列出所有可用的斜杠指令及说明，指令可点击快速输入。
#### `/bot-upgrade` — 升级指引
> **你**：`/bot-upgrade`
>
> **QQBot**：📌当前版本 / ✅当前已是最新版本 / ⬆️升级指引 / 🌟官方 GitHub 仓库
显示当前版本、更新状态、升级文档链接及官方仓库入口。
#### `/bot-logs` — 日志导出
> **你**：`/bot-logs`
>
> **QQBot**：📋 日志已打包（约 2000 行），正在发送文件… *（发送 .txt 文件）*
导出最近约 2000 行网关日志为文件，方便快速排查问题。
---
## 🚀 快速开始
### 第一步 — 在 QQ 开放平台创建机器人
1. 前往 [QQ 开放平台](https://q.qq.com/)，用**手机 QQ 扫描页面二维码**即可注册/登录。若尚未注册，扫码后系统会自动完成注册并绑定你的 QQ 账号。
> ⚠️ 机器人创建后会自动出现在你的 QQ 消息列表中，并发送第一条消息。但在完成下面的配置之前，发消息会提示"该机器人去火星了"，属于正常现象。
4. 在机器人页面中找到 **AppID** 和 **AppSecret**，分别点击右侧**复制**按钮，保存到记事本或备忘录中。**AppSecret 不支持明文保存，离开页面后再查看会强制重置，请务必妥善保存。**
> 详细图文教程请参阅 [官方指南](https://cloud.tencent.com/developer/article/2626045)。
### 第二步 — 安装 / 升级插件
**方式一：远程一键执行（最简单，无需 clone 仓库）**
```bash
curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh \
| bash -s -- --appid YOUR_APPID --secret YOUR_SECRET
```
一行命令搞定：下载脚本 → 清理旧插件 → 安装 → 配置通道 → 启动服务。完成后打开 QQ 即可开始聊天！
> 首次安装**必须**传 `--appid` 和 `--secret`。后续升级如已有配置：
> ```bash
> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
> ```
**方式二：本地脚本（已 clone 仓库时使用）**
```bash
# 通过 npm 安装
bash ./scripts/upgrade-via-npm.sh --appid YOUR_APPID --secret YOUR_SECRET
# 或通过源码安装
bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET
```
**常用参数：**
| 参数 | 说明 |
|------|------|
| `--appid