qqbot

用 Python 快速搭建 QQ 聊天机器人，实现自动回复和群管理

QQBot 是一个基于腾讯 SmartQQ 协议开发的 Python 聊天机器人框架。它解决了在 QQ 上快速搭建自动化对话机器人的问题，让开发者无需深入了解 QQ 协议细节，即可通过简单的接口实现消息收发、群聊管理、自定义回复等功能。核心能力包括：支持 SmartQQ 协议登录、接收和发送私聊/群聊消息、插件化扩展机制、基于图灵机器人等第三方 AI 的自动对话、定时任务和事件触发。项目结构清晰，API 设计简洁，适合个人开发者或小团队快速构建 QQ 机器人，用于自动回复、消息推送、群管理、娱乐互动等场景。虽然基于 SmartQQ 协议存在稳定性风险，但作为早期开源项目，它曾为许多 QQ 机器人爱好者提供了入门范例。

开源 free 对话助手

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 3683

维护状态低维护

是否开源是

定价模式 free

项目数据

分类对话助手

开发团队pandolia

所属国家

官网地址

GitHubhttps://github.com/pandolia/qqbot

定价模式free

价格说明开源项目，基于SmartQQ的QQ机器人，需自行部署，完全免费。

访问状态

是否开源是

开源协议NOASSERTION

主要语言Python

技术栈/模型chat,chatbot,python,qq,qqbot,smartqq,webqq

GitHub 星标★ 3683

30天Star增速

HF 下载量

上线时间2016-07-29 00:00:00

最近更新2026-09-23 00:00:00

维护状态低维护

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数6

使用教程

难度：入门约 10 分钟部署方式：本地安装 8 步

环境要求

Python 2.7 或 3.4+
可用的 pip 包管理工具
支持 Linux / Windows / Mac OSX
Linux 下需系统含 gvfs-open 或 shotwell 才能自动弹出二维码
Windows10 下需已设置 png 图片的默认打开程序

安装与启动步骤

1安装 qqbot

用 pip 直接安装。若已下载源码包，解压后进入目录执行 pip install . 效果相同。
```
pip install qqbot
```
2（可选）源码安装

下载源码压缩包解压后，进入源码目录再执行本地安装，适合需要改动源码的情况。
```
cd qqbot-master
pip install .
```
3启动 QQBot

在命令行直接输入 qqbot 即可启动，启动过程中会自动弹出二维码图片。
```
qqbot
```
4扫码授权登录

用手机 QQ 客户端扫描弹出的二维码并授权登录，成功后登录信息会保存到本地文件。
5恢复登录免扫码

下次启动可带上 QQ 号尝试从本地文件恢复登录信息，恢复失败或过期时才需要重新扫码。
```
qqbot -q 3497303033
```
6按用户配置启动

配置文件中的每个 item 代表一个用户，用 -u 指定后加载该用户下的各项配置。
```
qqbot -u somebody
```
7用 qq 命令操作

另开一个控制台窗口，用 qq 命令操作 QQBot，可先执行 qq help 查看全部命令。
```
qq help
```
8查看全部命令行参数

配置文件的每个选项都有对应命令行参数，且命令行优先级更高，可用 -h 查看格式。
```
qqbot -h
```

关键配置

配置项	必填	说明	示例
`termServerPort`	否	QQBot-term HTTP-API 服务器端口，监听 127.0.0.1，设为 0 则不开启	`8188`
`httpServerIP`	否	二维码 http 服务器 ip，应设置为公网 ip 或空字符串
`httpServerPort`	否	二维码 http 服务器端口号，服务器模式下访问二维码用	`8189`
`qq`	否	自动登录的 QQ 号，配合 qqbot -q 使用	`3497303033`
`mailAccount`	否	接收二维码图片的邮箱账号，用于邮箱模式显示二维码	`3497303033@qq.com`
`mailAuthCode`	否	邮箱 IMAP/SMTP 服务授权码，非邮箱登录密码	`feregfgftrasdsew`

如何确认成功

扫码授权后 QQBot 正常启动，并在另一控制台执行 qq help 能得到响应，说明启动成功。

常见问题

Q：这个项目现在还能用吗？

A：不能。README 明确声明 SmartQQ 已于 2019 年 1 月 3 日停止服务，本项目已无法使用且不再更新维护，仅可作学习参考。

Q：二维码图片没有自动弹出怎么办？

A：可手动打开图片文件扫码，或把二维码显示模式设为邮箱模式（配 mailAccount / mailAuthCode）、服务器模式（配 httpServerIP / httpServerPort）、文本模式（cmdQrcode）。

Q：登录信息能保存多久？

A：README 说明保存的登录信息一般在 2 天之后过期，过期后需要重新扫码登录。

Q：怎么查看全部命令行参数？

A：执行 qqbot -h 即可查看所有命令行参数格式，命令行参数优先级高于配置文件。

注意事项

重要：SmartQQ 已于 2019 年 1 月 3 日停止服务，本项目无法使用，不要再用于生产环境。
Linux 下需存在 gvfs-open 或 shotwell 命令，Windows10 下需设置 png 默认打开程序，才能自动弹出二维码。
配置文件位于 ~/.qqbot-tmp/v2.x.conf，首次运行后自动创建；其中根配置固定不可修改。
插件需放在系统 import 目录或 ~/.qqbot-tmp/plugins 目录下，也可通过 pluginPath 指定其他目录。

核心亮点

基于 SmartQQ 协议，无需登录网页版即可收发消息，接入门槛低
插件化架构，支持自定义命令和事件监听，扩展灵活
内置图灵机器人等 AI 对话接口，开箱即用实现智能聊天

不足之处

SmartQQ 协议已停止维护，登录可能失效，稳定性存疑
文档较少，依赖社区经验，新手上手有一定难度

适用场景

个人 QQ 自动回复和闲聊机器人
QQ 群管理，如入群欢迎、关键词提醒、自动踢人
消息推送，如定时发送天气、新闻、提醒

替代项目

NoneBot、go-cqhttp、Mirai

项目介绍

qqbot 是对话助手领域的开源项目，由 pandolia 开发，2016 年首次发布。

在全站 13,090 个收录项目中，它的 GitHub 星标数（3,683）位列前 30%，在对话助手分类的 907 个项目里位列前 8%。

项目已超过三个月没有代码更新，维护节奏明显放缓，最近一次代码更新于 2026-09-23。基于SmartQQ的QQ机器人，需自行部署，完全免费。

它主要面向的使用场景是：个人QQ自动回复和闲聊机器人。同类可对比的替代方案包括 NoneBot、go-cqhttp、Mirai。

上一篇：deep-chat

下一篇：Telegram.Bot