QQ Bot - 群聊小助手

功能特性

丰富的群聊功能，让你的群更加活跃有趣

音乐点歌

支持网易云音乐和 QQ 音乐搜索，发送音乐卡片，点击即可播放

互动游戏

成语接龙、猜歌游戏、抽签运势等多种互动游戏，让群聊不再无聊

美图分享

随机动漫图片、二次元插画，一键分享到群聊

天气查询

支持全国城市天气查询，提供实时天气和预报信息

每日外语

每日英语、每日日语，一句话学习地道外语表达

插件扩展

模块化插件架构，轻松扩展新功能，无需修改核心代码

命令一览

所有命令需要 @机器人才能触发，避免群聊刷屏

音乐

@我点歌 <歌名>网易云搜索，选序号发卡片

@我 QQ点歌 <歌名>QQ音乐搜索

@我歌词上一首歌歌词

@我每日一歌随机推荐

@我猜歌猜歌游戏

@我点歌排行点歌排行

@我点歌记录点歌足迹

互动

@我成语接龙接龙游戏

@我抽签今日运势

@我选择 A B C帮你选择

@我一言随机语录

@我美图动漫图片

@我插画插画风格

工具

@我天气 <城市>天气查询

@我每日英语英语学习

@我每日日语日语学习

@我帮助功能菜单

安装指南

快速部署到你的服务器或本地环境

1

克隆项目

从 GitHub 克隆最新代码到本地

git clone https://github.com/codehyq/qq-bot.git

2

配置环境

配置网易云 Cookie（可选，推荐配置以提升搜索准确度）

cd bot

echo "NETEASE_COOKIE=你的cookie" >> .env

从浏览器登录 music.163.com 提取 Cookie

3

启动服务

使用 Docker Compose 启动所有服务

docker compose up -d

4

配置 LLBot Desktop

下载并配置 QQ 机器人客户端

下载 LLBot Desktop，解压到固定目录
运行 llbot.exe，点击"启动"后用 QQ 小号扫码登录
打开 http://localhost:3080，配置反向 WebSocket

WebSocket 地址: ws://localhost:8080/onebot/v11/ws

AccessToken: (留空)

5

测试

在群里发送 @机器人帮助查看所有功能

环境要求

Docker Desktop

Windows 需开启 WSL2

LLBot Desktop

QQ NT 客户端

QQ 小号

已加入目标群聊

启动的容器

musicapi :13000

qqmusicapi :13300

nonebot :8080

常用命令

docker compose logs -f nonebot

查看 NoneBot 日志

docker compose up -d --build

重新构建并启动

使用文档

了解更多技术细节和开发指南

架构设计

QQ群消息 → LLBot Desktop (QQ NT 宿主)
           │ 反向 WebSocket (OneBot v11)
           ▼
      NoneBot2 (Python, :8080)
      ├── at_bot.py       # @机器人拦截器
      ├── music.py        # 点歌
      ├── music_extra.py  # 歌词/每日一歌/猜歌
      ├── idiom_chain.py  # 成语接龙
      ├── weather.py      # 天气
      ├── quote.py       # 一言
      ├── fortune.py      # 抽签
      ├── choose.py       # 选择困难症
      ├── daily_lang.py   # 每日英语/日语
      ├── image.py        # 美图
      ├── help.py         # 帮助菜单
      └── db.py          # SQLite 数据库
           │
      ┌────┴────┐
      ▼         ▼
 musicapi   qqmusicapi
(Netease)  (QQ Music)
 :13000     :13300

LLBot Desktop 运行在 Windows，整合 QQ NT 和 OneBot 协议
NoneBot 和 MusicAPI 在 Docker 中运行
反向 WebSocket 连接，无需暴露公网端口

插件开发

添加新功能只需简单几步

1 在 bot/plugins/ 下新建 .py 文件

2 导入 help_registry 并调用 register()

3 使用 on_command() 或 on_message() 注册处理器

4 NoneBot 自动加载，无需修改 bot.py

注意: 修改代码后执行 docker compose restart nonebot 生效

技术栈

Docker Compose 服务编排

NoneBot2 Python 机器人框架

nonebot-adapter-onebot OneBot v11 协议适配

httpx 异步 HTTP 客户端

aiosqlite 异步 SQLite

贡献指南

欢迎提交 Issue 和 Pull Request

提交 Bug 或功能建议提交代码改进给项目点个 Star

MIT License

常见问题

解决你可能遇到的常见问题

联系我们

有问题或建议？联系我们吧！

GitHub

codehyq/qq-bot

Issue Tracker

报告问题和建议

Star Fork

QQ 群聊小助手