Python QQ机器人如何实现基础功能？

99ANYc3cd6 机器人 2025-12-06 1

“Python QQ 机器人”这个话题，主要围绕着几个核心的库/框架展开，我会从最主流的方案讲起,并提供详细的入门指南。

（图片来源网络，侵删）

核心概念：为什么需要库？

QQ 官方并没有提供像 Telegram 那样开放、易于开发者接入的 Bot API，我们不能直接通过官方接口来接收消息和发送回复，所有 Python QQ 机器人都是通过“逆向工程”或“协议模拟”的方式实现的,即：

登录 QQ：模拟 QQ 客户端的登录过程。
监听消息：连接到 QQ 的消息服务器,监听收到的消息。
解析消息：将收到的原始数据（通常是二进制或特殊格式）解析成我们能看懂的文字、图片、@信息等。
发送消息：将我们想要回复的内容,通过协议发送给指定的好友或群聊。

由于这种方式依赖于非官方的协议，所以有以下重要前提：

风险：使用非官方接口有被腾讯封号的风险，特别是使用频繁或进行自动化操作时。请务必使用小号进行测试和运行。
稳定性：官方随时可能更新协议，导致机器人失效,你需要关注你所使用的库的更新动态。
功能限制：功能取决于库的实现能力,可能无法实现所有官方客户端的功能。

主流 Python QQ 机器人库/框架

目前最主流、最活跃的库是 go-cqhttp 配合 nonebot2，这是一个黄金组合，也是目前功能最强大、社区最活跃的方案。

`go-cqhttp` + `nonebot2` (强烈推荐)

这是目前最推荐的方案，它将复杂的底层协议处理和登录封装在 go-cqhttp (一个用 Go 语言写的程序) 中，然后通过反向 WebSocket 的方式，将消息数据传递给用 Python 写的 nonebot2 框架。nonebot2 负责处理业务逻辑,就像一个大脑。

（图片来源网络，侵删）

工作流程： QQ客户端 <-> go-cqhttp (协议层) <-> WebSocket <-> nonebot2 (逻辑层) <-> 你的Python代码

优点：

稳定可靠：go-cqhttp 社区活跃，更新快,对协议的跟进很好。
功能强大：支持几乎所有消息类型（文字、图片、表情、文件、群管等）,支持登录多账号。
Python生态：nonebot2 基于异步框架 asyncio，性能高,且拥有丰富的插件生态。
易于扩展：可以轻松编写自己的插件,或者安装别人写好的插件。

快速入门：`go-cqhttp` + `nonebot2`

第 1 步：安装 `go-cqhttp`

下载：访问 go-cqhttp 的 GitHub Releases 页面下载对应你操作系统的最新版本。
运行：
- Windows: 解压后，直接双击 go-cqhttp.exe。
- macOS/Linux: 在终端中进入解压目录，运行 ./go-cqhttp。
扫码登录：第一次运行会弹出一个二维码，使用手机 QQ 扫描登录即可，登录成功后，会在同目录下生成 config.yml 和 device.json 文件。

第 2 步：配置 `go-cqhttp`

编辑 config.yml 文件，找到 servers 部分，确保 ws_reverse 配置是开启的。

# config.yml
servers:
  - # 反向WS设置
    ws_reverse:
      # 正向WS服务器监听地址
      host: 0.0.0.0
      # 正向WS服务器监听端口
      port: 8080
      # 反向WS Universal地址
      # 注意: 格式为 ws://your_ip:your_port
      # 如果你是在本机运行，可以写 ws://127.0.0.1:8080
      universal: ws://127.0.0.1:8080
      # 是否开启正向WS服务器
      access_token: "" # 可选，如果设置了，nonebot连接时需要提供

universal: 这里填写 nonebot2 将要连接的地址。go-cqhttp 和 nonebot2 在同一台电脑上，就写 ws://127.0.0.1:8080。
保存文件后，重启 go-cqhttp。

第 3 步：安装和配置 `nonebot2`

创建项目目录：
（图片来源网络，侵删）
```
mkdir my_qq_bot
cd my_qq_bot
```

创建虚拟环境 (推荐)：

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

安装 nonebot2：
```
pip install nonebot2
```
初始化项目：
```
nb create
```
按照提示选择 nonebot2 的模板，推荐选择 advanced (高级) 模板，它包含了 go-cqhttp 的适配器。

配置 .env 文件：在项目根目录下，编辑 .env 文件，添加 go-cqhttp 的连接信息。

# .env
# 这里填写 go-cqhttp 的 ws_reverse 配置中的 universal 地址
WS_SERVER_URL=ws://127.0.0.1:8080
# 如果你在 config.yml 中设置了 access_token，也需要在这里填写
# ACCESS_TOKEN=your_token_here

第 4 步：编写你的第一个机器人插件

在 src/plugins 目录下（或你自定义的插件目录），创建一个新文件，hello.py。

在 hello.py 中编写代码：

# src/plugins/hello.py
from nonebot import on_command
from nonebot.adapters.onebot.v11 import Message, MessageSegment
from nonebot.matcher import Matcher
from nonebot.params import CommandArg
from nonebot.permission import SUPERUSER
# 使用 on_command 创建一个命令匹配器
# 'hello' 是命令名
# permission=SUPERUSER 表示只有超级用户（默认是机器人主人）能触发这个命令
hello_matcher = on_command("hello", permission=SUPERUSER)
@hello_matcher.handle()
async def handle_first_receive(matcher: Matcher, args: Message = CommandArg()):
    # args 是命令后面的参数，"hello world"，args "world"
    if args:
        # 如果有参数，直接回复
        await matcher.send(args)
    else:
        # 如果没有参数，回复一个固定的消息
        await matcher.send("你好！我是你的机器人！")
# 再来一个示例，发送图片
pic_matcher = on_command("get_pic")
@pic_matcher.handle()
async def handle_get_pic(matcher: Matcher):
    # MessageSegment.image 用于发送本地图片
    # 请确保你的项目根目录下有一张名为 'test.jpg' 的图片
    await matcher.send(MessageSegment.image("file:///C:/path/to/your/test.jpg")) # 注意：Windows下路径格式
    # 或者发送网络图片
    # await matcher.send(MessageSegment.image("https://gss0.baidu.com/70cFfyinKgQFm2e88IuM_a/baike/pic/item/0b7f21a4462309f7d7fc756f0de7ad438d4e4217.jpg"))

第 5 步：启动机器人

在项目根目录下,运行：

python bot.py

你的机器人就启动了！回到你的 QQ，给机器人发送 /hello 或 /hello 你好呀，它应该会回复你，发送 /get_pic,它应该会尝试发送一张图片。

其他方案（了解即可）

除了 go-cqhttp + nonebot2，还有一些其他的库，但它们要么已经过时,要么功能较少。

nonebot-adapter-onebot 这是 nonebot2 官方支持的适配器，它本身不处理登录，而是需要你配合一个能提供 OneBot 协议的 HTTP/WS 服务的后端。go-cqhttp 就是这样一个完美的后端，所以这个方案其实就是上面推荐的“黄金组合”。
Mirai / Mirai-Http-Adapter Mirai 是一个用 Kotlin 写的、非常强大的 QQ 机器人框架，它也有一个 HTTP API 提供给外部调用，Python 端可以使用 mirai-api-http 这个库来和 Mirai 通信。
- 优点：Mirai 本身功能极其强大，插件生态丰富（虽然大部分是 Kotlin/Java 的）。
- 缺点：需要运行一个 Java/Kotlin 环境，对新手不太友好，且 Mirai 的协议更新有时会导致不兼容。
qgbot / qqbot 这是一些比较早期的 Python QQ 机器人库，通常直接使用 aiohttp 等库模拟登录和收发消息，由于腾讯反爬虫和协议更新的压力，这些库大多已经停止维护，不推荐在新项目中使用。

机器人可以做什么？（插件生态）

nonebot2 的强大之处在于其插件生态，你不需要从零开始造轮子,可以直接安装和使用别人写好的插件。

安装插件：通常使用 pip install nonebot-plugin-xxx 的方式安装。

一些热门插件示例：

nonebot-plugin-chatgpt: 让机器人接入 ChatGPT,智能回复。
nonebot-plugin-bilibili: 监控 B �站动态,并在群里推送。
nonebot-plugin-weather: 查询天气。
nonebot-plugin-rss: 订阅 RSS 源,推送更新。
nonebot-plugin-mystool: 米游社工具，自动签到、领取奖励等。
nonebot-plugin-picsearcher: 以图搜图。

安装插件后，通常需要在 bot.py 中注册它。

总结与建议

特性	`go-cqhttp` + `nonebot2`	其他方案
推荐度	⭐⭐⭐⭐⭐ (首选)	⭐⭐ (仅作了解)
稳定性	高，社区活跃	较低或已过时
功能	极其强大，覆盖全面	有限或依赖环境
易用性	中等，需要分两步配置	较高 (单库) 或较低 (复杂环境)
扩展性	极高，丰富的插件生态	有限

给你的建议：

如果你是新手：请直接选择 go-cqhttp + nonebot2 方案，虽然看起来步骤多一点，但这是目前最稳定、功能最全、社区支持最好的方案,能让你走得更远。
务必使用小号：永远不要用你常用的、有重要联系人的 QQ 号来运行机器人,以防万一。
从简单开始：先实现最简单的“复读机”或“命令回复”,再逐步尝试更复杂的功能和插件。
多看文档：nonebot2 和 go-cqhttp 的官方文档是你的好朋友,遇到问题先查文档。