企业官网建设流程全解析

QQBot 快速上手：5分钟跑通你的第一个QQ自动回复机器人

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

如果你管理着几个QQ群，一定经历过这样的时刻：同样的"怎么进群""今天打卡了吗"被问了一百遍，你复制粘贴到手酸；说好每晚十点发提醒，结果一忙就忘；半夜想看服务器状态，还得爬起来开电脑。QQBot 就是来解决这类问题的——它是一款基于腾讯 SmartQQ 协议的 Python 开源框架，用最直白的话说：让你用几行代码，把 QQ 里的自动回复、定时提醒、消息监控全部包办。这个项目跨平台（Linux / Windows / macOS），支持插件化扩展，对新手友好到"写一个函数就能上岗"。

一、QQBot 是什么？把 QQ 变成你的"代码遥控器"

你可以把 QQBot 想象成一位24 小时不喊累的在线接线员：它替你登录一个 QQ 号，帮你盯着每一条进来的消息，然后按你写好的规则决定"该回什么、该发给谁、什么时候发"。

它和普通脚本最大的区别在于可交互——不是一次性跑完就结束，而是持续在线、持续监听、持续响应。核心能力可以用一张表看清：

值得说明的是，QQBot 官方并未提供"现成聊天 AI"，它是一个框架——你提供逻辑，它负责跑腿。也正因如此，它的能力边界由你的想象力决定。

二、理解 QQBot 的核心思想：一切皆回调

上手前，先花 30 秒理解这个框架最关键的机制，后面会事半功倍。

QQBot 把"程序运行时发生的各种事件"统一抽象成了9 种回调函数，你只要在插件文件里写好这些函数，框架就会在对应时机自动调用它们：

• onInit：插件初始化
• onQrcode：拿到登录二维码
• onStartupComplete：启动完成
• onQQMessage：收到新消息（最常用）
• onInterval：每 5 分钟触发一次
• onUpdate：联系人列表更新
• onPlug/onUnplug：插件被加载/卸载
• onExit：程序退出

其中onQQMessage是你最常用的入口。函数名和参数必须原样保留，框架靠签名识别它们——这是新手最容易踩的坑。所有回调的完整示例在qqbot/plugins/sampleslots.py里，建议先通读一遍。

三、5分钟快速上手：从空目录到第一个机器人

第 1 步：获取代码并安装依赖

项目要求 Python 2.7 或 3.4+，用 pip 安装依赖即可：

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

💡 想装在隔离环境避免污染系统 Python？项目仓库里提供了qqbot-venv.sh脚本，可直接创建独立虚拟环境。

第 2 步：启动主程序并扫码登录

qqbot

程序启动后会自动弹出二维码（Linux 需要系统装有 gvfs-open 或 shotwell），用手机 QQ 扫码授权即可。登录信息会保存在本地，下次用qqbot -q qq号码启动可免扫码快速登录（注意保存的凭证约 2 天后过期）。

第 3 步：写你的第一个插件

新建文件sample.py，内容如下：

def onQQMessage(bot, contact, member, content): if content == '-hello': bot.SendTo(contact, '你好，我是QQ机器人') elif content == '-stop': bot.SendTo(contact, 'QQ机器人已关闭') bot.Stop()

这段代码让机器人遇到-hello就打招呼，收到-stop就自动下线。把文件放到~/.qqbot-tmp/plugins/目录，然后在另一个终端窗口执行：

qq plug sample

至此，你的第一个 QQ 自动回复机器人已经上线 🎉。想卸载就执行qq unplug sample，整个过程无需重启主程序——这就是插件热插拔。

四、3个拿来即用的实战模板

掌握了入口函数，剩下的就是写业务逻辑。下面三个模板都摘自项目官方文档与示例，可以直接改改套用。

模板一：群内"被@"友好应答

QQBot 会智能识别"有人@你"：消息中带@ME标记就说明本机器人被点名了，这时候才回应，避免骚扰群友：

def onQQMessage(bot, contact, member, content): if '@ME' in content: bot.SendTo(contact, member.name + '，艾特我干嘛呢？')

模板二：定时群发提醒（11:55 和 17:55 自动开饭广播）

定时任务用qqbotsched装饰器，参数沿用 Unix crontab 语法，支持hour、minute、day_of_week等 11 个字段：

from qqbot import qqbotsched @qqbotsched(hour='11,17', minute='55') def mytask(bot): gl = bot.List('group', '456班') if gl is not None: for group in gl: bot.SendTo(group, '同志们：开饭啦啦啦啦啦啦！！！')

⏰ 这是它内部对 apscheduler 的轻量封装——想每 5 分钟跑一次写minute='*/5'，想工作日跑写day_of_week='mon-fri'。

模板三：用命令行远程指挥

qq命令工具可以让你在另一个终端直接操控机器人，连代码都不用写：

qq send buddy jack 你好 # 给好友 jack 发消息 qq list group 机器人测试 # 搜索名含"机器人测试"的群 qq list group-member 456班 # 查看群成员 qq send group 198班 大家好 # 给群发消息

配套的 HTTP 接口（默认监听127.0.0.1:8188）让 Web 前端也能调用同样的能力，比如通过send/buddy/jack/hello这类 URL 发送消息。

五、它内部是怎么跑的？一张图看懂运行机制

QQBot 的架构是典型的"主线程管生命周期，子线程干杂活"，设计清晰，值得借鉴：

程序的生命周期可以拆成四个阶段：

1. 登录阶段：读取配置 → 加载插件（触发onInit）→ 获取二维码（触发onQrcode）→ 等待扫码授权。
2. 启动阶段：登录成功后（可选）拉取联系人列表，触发onStartupComplete，随后同时拉起 4 个子线程——消息轮询线程、每 5 分钟的 interval 线程、本地 term-server 线程（8188 端口）、定时调度线程。
3. 运行阶段：主循环持续运转，消息一到就触发onQQMessage，定时到点就执行qqbotsched任务，所有插件回调都在主线程依次串行执行——所以不用担心全局变量线程安全，但回调里也千万别做耗时操作，否则会阻塞整个程序。
4. 退出阶段：手动停止、重启或登录过期时触发onExit，父进程再根据退出码决定是否自动重启。

值得一提的是，框架内置了掉线自动重启（restartOnOffline）和定时重启插件（qqbot/plugins/schedrestart.py），配合邮箱接收二维码，能让机器人长期稳定在线。

六、新手避坑清单（都是血泪经验）

• 回调签名不能改：onQQMessage(bot, contact, member, content)四个参数一个都不能少、名字不能换，否则函数不会被识别。
• 不是所有联系人能发消息：bot.SendTo只能发给好友/群/讨论组，不能发给群成员对象（member）。
• 判断消息类型：看contact.ctype，取值为buddy/group/discuss，分别对应好友消息、群消息、讨论组消息。
• 别在回调里调外部命令：绝对不要用os.system('qq send ...')去操作自己这个 QQ，会和主程序形成死锁，请直接用bot.SendTo等内置接口。
• 配置按层级覆盖：根配置 → 默认配置 → 用户配置 → 命令行参数，优先级依次递增。改了配置不生效？多半是你没按qqbot -u 你的用户名启动。
• 文件名避开关键字：别把自己的脚本命名为qqbot.py、sys.py，也别在代码里用qqbot/sys/time做变量名，很容易和库冲突。
• 重复发消息的处理：SendTo有个resendOn1202参数（默认True），设成False可避免偶发重复发送，代价是可能漏发，按需取舍。

七、常见问题速查

Q1：二维码弹不出来怎么办？A：QQBot 一共提供 4 种二维码显示模式：GUI 弹窗（默认）、邮箱模式（配置mailAccount和mailAuthCode，推荐 QQ 邮箱）、服务器模式（需公网 IP）、文本模式（cmdQrcode设为true，需装 pillow 和 wcwidth）。远程服务器上用邮箱模式最省心。

Q2：如何稳定长期在线？A：SmartQQ 协议限制下登录凭证 1~2 天必失效，需重新扫码。实操方案是：开启邮箱模式 +restartOnOffline自动重启 + 加载schedrestart插件每天固定时间重启一次（比如每天 8:00），用手机顺手扫一下即可。

Q3：怎么拿到消息发送者的 QQ 号？A：用onQQMessage的第 2、3 个参数，contact.qq/contact.name/contact.mark等属性都在联系人对象上，各字段含义详见qcontact-attr.md。注意member在好友消息时为None。

Q4：能发图片、文件、语音吗？A：不能。SmartQQ 协议本身不支持发送图片、文件、音频及 XML 卡片消息，群内也无法真正 @ 其他成员（对方只会收到纯文本）。这是协议层面的硬限制，不是配置能解决的。

八、给新手的 3 阶段学习路线

1. 入门：通读根目录README.MD弄懂基本概念 → 跑通qqbot/plugins/sample.py示例 → 把qqbot/plugins/sampleslots.py里的 9 种回调都打印一遍日志，感受触发时机。
2. 进阶：精读README.MD中bot.List / Update / SendTo三个核心接口的返回值语义 → 用qqbotsched写出你的第一个定时任务 → 研究qqbot/plugins/schedrestart.py的插件写法。
3. 实战：在plugins-in-dev/目录看社区插件（如patchfetch.py如何覆写联系人获取逻辑）→ 参考配置文件写多用户配置 → 尝试用 HTTP API 给你的机器人做一个 Web 控制台。

写在最后：关于项目现状的诚实说明

需要向读者说明一个事实：QQBot 基于腾讯 SmartQQ 协议构建，而该官方接口已于 2019 年停止服务，因此本项目目前已无法实际登录使用，项目也早已停止维护（项目作者在 README 顶部明确标注了这一点）。文章中的示例代码与运行机制描述，均来自项目真实源码与官方文档。

尽管如此，QQBot 依然是学习 Python 机器人框架设计的一流教材：它的插件热加载机制、回调事件模型、定时任务封装、多线程生命周期管理，至今仍有很高的参考价值。如果你正在设计自己的消息机器人或自动化框架，读它的源码会收获颇多。

核心资源导航

• 官方文档：README.MD（最完整的接口说明，务必先读）
• 最简单示例：qqbot/plugins/sample.py（一个文件学会自动回复）
• 全部回调示例：qqbot/plugins/sampleslots.py（9 种回调逐个演示）
• 定时重启插件：qqbot/plugins/schedrestart.py
• 开发中插件：plugins-in-dev/（含patchfetch.py等高阶玩法）
• 表情关键词表：qqbot/facemap.py（消息里可嵌入/可爱等表情）
• 联系人属性说明：qcontact-attr.md
• 常见问题汇总：faq.md

看懂架构、跑通示例、再动手写一个属于自己的回调——自动化带来的爽感，只有试过才知道。开始吧 🚀

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