5分钟跑通QQ机器人：QQBot开源框架零基础上手全攻略

【免费下载链接】qqbotQQBot: A conversation robot base on Tencent's SmartQQ项目地址: https://gitcode.com/gh_mirrors/qq/qqbot

下午三点，客服群的小周已经第八次复制粘贴同一个答案了。群里的问题永远是那几个：价格、发货、售后。这样的日子，相信很多群主、运营和开发者都懂。其实这件事有个更省力的解法：写一个QQ机器人，把重复回答、定时提醒交给代码，你就能从"人工客服"里解放出来。今天的主角QQBot，就是这样一个开源的Python QQ机器人框架，它帮你自动收发消息、管理联系人、定时执行任务，5分钟就能跑起来。

QQBot是什么？一句话说清

一句话：QQBot是一个基于Python和腾讯SmartQQ协议的开源QQ机器人框架。你可以把它想象成一个"会编程的QQ管家"——它替你登录一个QQ账号，然后由代码接管这个账号的所有消息处理。你只需要写几个函数，告诉它"收到什么话就回什么话""每天几点发提醒"，剩下的事它全包了。

下面直接上手，先跑起来再讲道理。

三步完成QQ机器人快速上手

第1步：安装QQBot依赖

克隆仓库并安装，前提是电脑上已有Python（2.7或3.4+）：

git clone https://gitcode.com/gh_mirrors/qq/qqbot cd qqbot pip install .

装好后，命令行里就有了qqbot和qq两个命令，前者负责启动机器人，后者负责操控机器人。

第2步：启动并扫码登录

直接运行：

qqbot

程序会自动弹出二维码图片，用手机QQ扫码授权即可。登录成功后，登录信息会保存在本地，下次启动时用qqbot -q 你的QQ号可以免扫码快速登录（有效期约2天）。

第3步：跑通第一个自动回复

在~/.qqbot-tmp/plugins/目录下新建mybot.py，写入：

def onQQMessage(bot, contact, member, content): if content == '-hello': bot.SendTo(contact, '你好，我是QQ机器人') # 收到 -hello 就回复这句 elif content == '-stop': bot.SendTo(contact, 'QQ机器人已关闭') bot.Stop() # 收到 -stop 就自动下线

然后在另一个终端窗口执行qq plug mybot加载插件。现在，用另一个QQ给这个账号发-hello，就能收到自动回复了。

核心能力：按真实场景看它能做什么

跑通之后，你会发现核心玩法就三类：回复、定时、查询。分别对应下面的场景。

场景一：群里的智能客服

把常见问题整理成规则，24小时在线应答：

def onQQMessage(bot, contact, member, content): if '价格' in content: bot.SendTo(contact, '现在下单立减20元，包邮哦') elif '发货' in content: bot.SendTo(contact, '下单后24小时内发货')

这段代码解决的是"人肉客服"的重复劳动——规则写好后，同一个问题问一百遍，答案都不带跑偏。

场景二：定时打卡与提醒

用qqbotsched装饰器设定时间，到点自动发消息：

from qqbot import qqbotsched @qqbotsched(hour='22', minute='0') # 每晚22:00触发 def checkin_remind(bot): groups = bot.List('group', '学习打卡群') # 先找到目标群 for group in groups: bot.SendTo(group, '打卡时间到，回复"已打卡"完成今日记录')

它解决的是"总是忘记发提醒"的问题，会议通知、早安问候、定时巡检都能这么写。

场景三：群消息监控与远程控制

在回调里判断消息来源和内容，就能实现"被@才应答"或"远程下指令"：

def onQQMessage(bot, contact, member, content): if '@ME' in content: # 群成员@机器人时触发 bot.SendTo(contact, member.name + '，找我什么事？') if content == '-server': bot.SendTo(contact, '服务器运行正常，CPU占用 12%')

比如服务器状态异常，直接在群里发个-server，机器人立刻回报情况——这就是最简单的远程控制。

运行原理：它内部是怎么工作的

看上面的架构图，QQBot采用的是"主线程 + 子线程"的分工模式，理解这几点就够了：

1. 登录阶段：主线程依次完成读取配置、加载插件、获取二维码、等待扫码授权；
2. 消息轮询：登录后启动一个子线程持续向服务器轮询新消息，收到的消息统一交给onQQMessage处理；
3. 定时任务：另一个子线程负责调度qqbotsched注册的任务，到点触发；
4. 命令端口：子线程在 8188 端口监听，qq命令和 HTTP API 都走这条路；
5. 回调驱动：所有插件行为都通过onInit、onQQMessage、onInterval等回调函数接入主循环，插件之间互不干扰。

这套设计的妙处在于：你只需要写回调函数，完全不用关心网络、线程这些底层细节。

进阶技巧：插件化与配置管理

插件化开发：每个功能一个.py文件放到插件目录，用qq plug 插件名随时加载、qq unplug 插件名卸载，不必重启整个机器人。把问候、提醒、监控拆成独立插件，改一处不影响其他。

配置管理：配置文件位于~/.qqbot-tmp/v2.x.conf，支持多用户配置。比如想让机器人掉线后自动重启、每天固定时间重启一次保持在线，可以在配置里这样写：

{ "mybot": { "qq": "123456789", "restartOnOffline": true, "plugins": ["mybot", "qqbot.plugins.schedrestart"] } }

启动时用qqbot -u mybot加载这组配置。定时重启插件配合自动重启开关，能让机器人长期稳定在线。

新手最容易踩的几个坑

1. 二维码弹不出来：Linux下需要系统装了gvfs-open或shotwell。实在不行，在配置里开启cmdQrcode用文本模式显示二维码，或配置邮箱接收二维码图片。
2. 机器人总是掉线：SmartQQ协议每1~2天会强制下线，这是协议本身的限制。解决办法是开启restartOnOffline，并每天固定时间扫码重新登录一次。
3. 消息偶尔重复发送：这是QQ服务器返回代码1202导致的。可在SendTo时传resendOn1202=False关闭重发，代价是有时消息发不出去，按需取舍。
4. 回调函数写太重，机器人变卡：所有回调都在主线程里顺序执行，不要在回调里做耗时操作（比如下载大文件），单次执行尽量控制在5秒内。
5. 想给群成员单独发消息却发不出去：协议只允许给好友、群、讨论组发消息，不能直接SendTo群成员对象，这是设计限制。

学习路径：从入门到实战

• 入门：跑通上面的示例，把 sample.py 改着玩，理解onQQMessage的参数含义；
• 进阶：研读 sampleslots.py 了解全部回调函数，再用qqbotsched做出你的定时任务；
• 实战：参考 schedrestart.py 和 plugins-in-dev/ 里的开发中插件，模仿它们的结构写出自己的业务插件。

下一步，动手

1. 克隆项目、安装依赖、扫码登录，先把自动回复跑通；
2. 把你最常被问的三个问题写成回复规则；
3. 加一个定时提醒，让机器人替你值班。

想深入的话，项目根目录的 README.MD 是完整的官方文档，faq.md 收集了更多常见问题，示例插件在 qqbot/plugins/ 目录下。现在就打开终端，让第一个QQ机器人上线吧。

【免费下载链接】qqbotQQBot: A conversation robot base on Tencent's SmartQQ项目地址: https://gitcode.com/gh_mirrors/qq/qqbot