Post

使用 NoneBot 搭建 QQ 机器人

搭建自己的 QQ 机器人

使用 NoneBot 搭建 QQ 机器人

最近在尝试搭建 QQ 群聊机器人,问了一下前辈,了解到 QQ 现在已经有了比较完善的官方支持,开源项目 NoneBot 也可以作为后端。但是实际查看 NoneBot 的文档的时候,连这个项目具体是什么作用、最后的机器人框架是什么样子都没搞清楚。网上的教程良莠不齐,要么有些已经严重过时了,遂将个人搭建 QQ 机器人的过程和心得记录一下。

创建 QQ 机器人

官方的 QQ 机器人应该已经很完善了,可以前往 QQ 机器人后台直接创建,过程非常简单。机器人创建后会自动成为 QQ 好友。

进入机器人的开发设置,记下 AppID 和 AppSecret,后面要用。

APPID 接入凭证

初始化项目

nb-cli 是很方便的脚手架,可以用于创建、管理和启动 NoneBot 项目。建议使用 uv pipx 等包管理工具将其全局安装:

1
uv tool install nb-cli # nb is here: ~/.locals/bin

使用 nb create 创建一个新项目,基础配置:

1
2
3
4
5
6
7
8
9
10
11
$ nb create
[?] Select a template to use: simple (for plugin developer)
Loading adapters...
Loading drivers...
[?] Project Name: your-bot-name
[?] Which adapter(s) would you like to use? QQ (QQ 官方机器人)
[?] Which driver(s) would you like to use? HTTPX (HTTPX 驱动器), websockets (websockets 驱动器)
[?] Which strategy of local storage would you like to use? Current project (suitable for multiple/portable instances)
[?] Where to store the plugin? 2) In a "src" folder
[?] Which developer tool(s) would you like to use?
[?] Install dependencies now? n

进入项目目录,安装依赖(如果在创建的选择了立刻安装依赖,应该可以跳过这一步):

1
2
3
uv sync
# https://stackoverflow.com/questions/77442172/ssl-certificate-verify-failed-certificate-verify-failed-unable-to-get-local-is
uv add pip-system-certs

配置机器人

QQ 机器人默认使用 WebSocket 支持事件订阅与回调;另一个方式是 Webhook,但是需要开通公网服务。对于日常使用,ws+httpx 就足够了。NoneBot 启动的时候会加载项目根目录 .env 中的变量,在此处声明:

1
DRIVER=~httpx+~websockets

之前记下的 AppID 和 AppSecret 也要声明在环境变量中,这里建议是根据实际用途加到对应的开放/生产 .env 中。例如,调试用的机器人连接信息放在 .env.dev 中:

1
2
3
4
5
6
7
8
9
QQ_BOTS='[
  {
    "id": "<AppID>",
    "secret": "<AppSecret>",
    "intent": {
      "c2c_group_at_messages": true
    }
  }
]'

这部分配置可以具体参考 NoneBot2 QQ 适配器的 README 文档。c2c_group_at_messages 是常用的基础配置项,打开后机器人可以接受私聊和群聊中 @ 自己的消息。

启动并连接机器人

可以在 src/plugins 下面增加一个简单的测试用插件:

1
2
3
4
5
6
7
from nonebot import on_command
from nonebot.adapters import Message
from nonebot.params import CommandArg
hello = on_command("hello")
@hello.handle()
async def handle_function(args: Message = CommandArg()):
    await hello.finish("Hello!")

在项目根目录运行 nb run,脚手架会自动加载虚拟环境并启动当前项目。如果提示到有证书验证问题,可以尝试安装 pip-system-certs 包解决:

1
uv add pip-system-certs

我在 macOS 本地开发时没有遇到这个问题,但是尝试部署到服务器上的时候遇到了。其实我也不甚了解其原理,解决方案来源于 Stack Overflow。

启动成功后至少会看到以下提示:

1
2
3
4
5
11-16 19:06:51 [DEBUG] nonebot | QQ | QQ api base url: https://api.bot.qq.com/
11-16 19:06:51 [INFO] nonebot | Application startup completed.
11-16 19:06:51 [DEBUG] nonebot | QQ | Bot <AppID> calling API shard_url_get
11-16 19:06:52 [DEBUG] nonebot | QQ | WebSocket Connection to wss://api.sgroup.qq.com/websocket established
11-16 19:06:52 [INFO] nonebot | QQ | Bot <AppID> connected

同时 QQ Bot 管理平台会显示 Bot 在线,可以在 QQ 中对其私聊 /hello 测试效果。

后记

这是一篇非常基础的 QQ 机器人上手教程,旨在帮助读者快速进行项目启动,进入后续的业务逻辑实现阶段。如今的绝大部分业务需求都可以通过“向 AI 许愿”快速完成,因此我觉得写一篇详细的 NoneBot 开发笔记就没有什么必要了。

在我写这篇博客的时候,发现知名的第三方 QQ 机器人框架 NapCat 刚刚删库跑路了。大约是又被商业公司大手了吧……第三方机器人的自由度确实要胜出官方机器人,但后者还算是比较适合小白的稳定方案。我也无从评判谁对谁错,但是看到优秀的开源项目又因为“利益”原因被迫跑路,还是觉得有些遗憾 🫠。

This post is licensed under CC BY 4.0 by the author.