QQBot 快速上手指南一个 QQ 群管小哥的救赎之路【免费下载链接】qqbotQQBot: A conversation robot base on Tencents SmartQQ项目地址: https://gitcode.com/gh_mirrors/qq/qqbot如果你也曾在深夜里一边给群友解释第 108 遍怎么改群名片一边盘算着要不要把群主之位拱手让人那么接下来的三分钟很可能改变你的群管生涯。我是小林一个被 QQ 群日常琐事逼疯的野生管理员直到我遇见了 QQBot——一个用 Python 写成的开源 QQ 机器人框架我的噩梦才算真正结束。一、先聊聊为什么你需要一个会编程的 QQ 管家先别急着划走我帮你回忆几个扎心瞬间新人进群你要手打一遍欢迎语 群规 入群改名片三连一天八遍手指头都快磨出老茧每晚十点你得掐着秒表去群里发打卡提醒偶尔忘一次第二天就被艾特到怀疑人生有人反复问多少钱怎么发货售后找谁你复制粘贴到手软对方还嫌你回复慢。而 QQBot 能做的恰恰是把这些低价值重复劳动全部接盘自动回复、定时播报、关键词匹配、群成员信息查询、甚至远程控制设备——只要你能想到的脚本逻辑它都能按你的指令在 QQ 上跑起来。一句话总结它的定位QQBot 是一个基于腾讯 SmartQQ 协议的开源框架让你用几行 Python 代码把任何 QQ 账号改造成 7×24 小时在线的自动应答机。二、先别急着装把三件套概念搞清楚在动手之前你得先理解 QQBot 的三个核心角色不然接下来会看代码看到头晕角色它是谁你要关心的QQBot 对象bot机器人的大脑中枢提供List、SendTo、Stop、Restart等接口QContact 对象contact消息的发送者有ctype/qq/uin/nick/mark/card/name等只读属性member 参数群消息里真正发言的那位好友私聊时它是None群聊时才有值有个新手极易踩的坑我必须先敲黑板bot.SendTo(member, ...)是非法操作。你只能给好友、群、讨论组发消息不能直接对群成员这个对象发消息。想给某个群友发私信老老实实先bot.List(buddy, 他的昵称)把好友对象找出来。三、从零安装五分钟跑通你的第一个 QQ 机器人安装过程简单到让人想哭前提是你电脑里有 Python2.7 或 3.4 均可git clone https://gitcode.com/gh_mirrors/qq/qqbot cd qqbot pip install .装完之后命令行敲下魔法咒语qqbot程序会自动弹出一张二维码掏出手机 QQ 扫一扫完成授权你的机器人就上线了。更贴心的是登录凭证会被保存在本地文件里下次启动时输入qqbot -q 你的QQ号就能免扫码直接登录——当然这份凭证大概两天后过期过期了还得乖乖再扫一次这点后面我会专门讲怎么续命。四、实战第一步写一个会打招呼、报时间的群管家现在让我给你展示什么叫三行代码改变命运。在插件目录默认是~/.qqbot-tmp/plugins/新建一个文件比如叫helper.py敲入# -*- coding: utf-8 -*- def onQQMessage(bot, contact, member, content): if content 你好: bot.SendTo(contact, 你好呀我是这个群的机器人小管) elif 现在几点 in content: from datetime import datetime now datetime.now().strftime(%Y-%m-%d %H:%M:%S) bot.SendTo(contact, 现在是 now)保存后保持 qqbot 进程在跑另开一个终端窗口执行qq plug helper插件挂载成功的那一瞬间你再去群里发一句你好试试——机器人秒回这感觉就像给群请了个不要工资的实习生。完整示例可参考项目里的 qqbot/plugins/sample.py功能虽简但五脏俱全。五、进阶玩法让机器人学会按时打卡只做自动回复那还只是开胃菜。QQBot 真正的杀手锏是内置的定时任务系统——qqbotsched装饰器。它的参数采用类 Unix crontab 格式简单、直观、好记。比如每晚十点提醒群友打卡你可以这样写from qqbot import qqbotsched qqbotsched(hour22, minute0) def daily_reminder(bot): 每晚10点整执行 groups bot.List(group, 学习打卡群) if groups is not None: for group in groups: bot.SendTo(group, 今日打卡时间到请回复已打卡完成记录~)这装饰器一共支持 11 个关键字参数year、month、day、week、hour、minute……可以拼出几乎任何你想要的执行节奏minute0-55/5每 5 分钟跑一次hour8,12,18, minute0每天 8 点、12 点、18 点整点触发day_of_weekmon-fri只在工作日执行定时任务的函数签名是铁律参数必须且只能有一个名字必须叫bot。别问问就是框架约定。六、扒一扒 QQBot 的内脏它到底是怎么转起来的好奇宝宝可能会问我写个函数它怎么就能在 QQ 上自动跑呢项目自带的架构图给出了完整答案这张图来自 doc-data/main.png把整个运行机制画得明明白白我帮你翻译成人话登录阶段主线程读配置 → 加载插件 → 触发onInit()→ 获取二维码 → 等待手机授权。登录成功后再触发onPlug()、onStartupComplete()此时你的插件才真正活过来。运行阶段主循环主线程进入一个死循环依次处理onQQMessage()消息、onInterval()每 5 分钟的心跳、终端命令、调度任务等事件。并行子线程四个子线程各司其职——消息轮询、5 分钟休眠计时、8188 端口 Web 服务监听、定时任务调度。互不干扰谁也不会卡住谁。除了onQQMessage框架还预留了onInit/onQrcode/onInterval/onUpdate/onPlug/onUnplug/onExit等一大票回调钩子全部示例在 qqbot/plugins/sampleslots.py 里照葫芦画瓢就能扩展出各种花活。七、把联系人玩明白搜群、查成员、发消息的一条龙操作日常群管最频繁的操作是什么找人、找人、还是找人。QQBot 的qq命令和bot.List()接口把联系人查询做得跟搜索引擎一样顺手。几个高频姿势都在qq命令下# 列出所有好友 qq list buddy # 按名称模糊搜索群 qq list group :like:测试 # 列出456班群的全部成员 qq list group-member 456班 # 找出群里名片为 mike 的成员 qq list group-member 456班 cardmike # 直接给好友jack发消息 qq send buddy jack 你好在代码里则是调用bot.List它会在本地联系人数据库里查查不到再去服务器拉取并缓存省时省流量。注意三点List返回的是QContact 对象列表不是字符串要用.qq、.name取属性返回[]表示没匹配到返回None表示服务器拉取失败——务必分情况判断再往下走Update接口可以强制刷新某类联系人缓存2000 人的大群成员列表刷新也就一两秒快到离谱。哦对如果你不想写代码也可以直接调 HTTP API——机器人启动后本机 8188 端口就是现成的接口服务比如浏览器里访问http://127.0.0.1:8188/send/buddy/jack/hello就能发消息前端同学狂喜。八、避坑手册资深玩家的血泪经验新增章节这部分是文档里散落的雷区我替你集中排一遍雷每一条都是我和无数前浪用头发换来的雷区 1消息莫名其妙发不出去或重复发腾讯服务器偶尔会返回 1202 错误码语义含糊——可能失败。SendTo默认会重试最多 3 次来确保送达代价是偶尔出现重复消息。想不重发就把参数关了bot.SendTo(contact, 这条消息只发一次, resendOn1202False)雷区 2机器人自己发的消息自己也会收到对你没看错。你的 QQ 发出去的消息也会流经机器人所以回调里一定要用bot.isMe(contact, member)过滤否则机器人会对自己的话作出回应形成自嗨死循环。雷区 3永远不要在回调函数里调os.system(qq send ...)这是官方文档盖章的死锁陷阱os.system要等命令执行完才返回而命令要等主线程空闲才执行——两边互相等待程序直接僵死。想发消息请用bot.SendTo。雷区 4回调函数里别做重活所有回调都在主线程里串行执行谁在里面 sleep 十秒全体消息就得排队等你。每个函数尽量控制在 5 秒内。雷区 5被艾特的误判如果群里有人的昵称和你的昵称前缀相同你叫 ab他叫 abc艾特他时可能会误判成艾特你。这是协议层的怪癖改个群名片就能绕开。更多细节见 faq.md 与 qcontact-attr.md。九、配置这件事一台机器怎么管住多个 QQQQBot 的配置文件首次运行后自动生成在~/.qqbot-tmp/v2.x.confJSON 格式一眼就能看懂。它支持多用户配置在文件里给每个 QQ 号开一个配置项然后用qqbot -u 用户名指定用哪套配置启动。我贴一份我自己的配置骨架供你参考{ mybot: { termServerPort: 8188, qq: 3497303033, restartOnOffline: true, plugins: [helper, schedrestart], pluginsConf: { qqbot.plugins.schedrestart: 8:00 } } }几个关键选项的作用记住这几个就够了配置项干什么用的termServerPort命令行/HTTP 服务端口设为 0 则关闭外部控制qq自动登录的 QQ 号restartOnOffline掉线后自动重启在线率的保障cmdQrcode开启文本模式二维码免图形界面扫码mailAccount/mailAuthCode二维码发到邮箱远程服务器福音plugins/pluginPath启动时自动加载的插件清单和插件目录配置优先级是固定链条根配置 → 默认配置 → 用户配置 → 命令行参数后加载的覆盖先加载的。改配置不生效先检查你是不是改错了层级。十、让机器人永不掉线的三板斧SmartQQ 协议的硬伤登录凭证 12 天后必失效腾讯会强制踢下线。但别慌有三个招叠加使用能把在线率拉到 95% 以上开启restartOnOffline掉线自动拉起进程先自动续命一次加载定时重启插件项目自带 qqbot/plugins/schedrestart.py默认每天 8:00 执行一次fresh-restart配合pluginsConf自定义时间配置邮箱模式收二维码把二维码直接发到邮箱手机 QQ 秒收通知长按即扫扫码体验行云流水。这三板斧下来基本就是每天固定扫一次码其余时间机器人都乖乖在线。十一、它还能这么玩从密码登录到 IRC 客户端你以为这就完了QQBot 的生态比你想的丰富免扫码登录插件 passwordlogin.py 借助 selenium 自动化浏览器完成用户名密码登录彻底告别人工扫码需装 selenium 和浏览器驱动Linux 极客玩法加载 miniirc.py 插件后机器人会在 6667 端口开一个微型 IRC 服务器用 weechat、irssi 这些终端客户端就能躺着聊 QQ热插拔机制qq plug 插件名/qq unplug 插件名随时挂载卸载跑着的进程不用重启插件想换就换发送表情消息里嵌入/微笑、/可爱这类关键词就能发 QQ 表情完整对照表在 facemap.py 里。十二、最后说两句掏心窝的话说实话第一次看到这个项目时我是有点将信将疑的——一个开源 QQ 机器人能有多强但当我真正把自动回复、定时打卡、群成员查询全部跑通之后我只想说一句真香。现在的我每天到点有人帮我喊打卡新人进群有人替我发欢迎语群友问价格我连手指都不用动。省下来的时间够我多刷十集剧。所以别光看别人家的机器人流口水了。克隆项目、装好依赖、写第一个onQQMessage、qq plug挂上去——属于你自己的 QQ 智能助手三十分钟就能诞生。动手吧你的群友在等你惊艳全场。【免费下载链接】qqbotQQBot: A conversation robot base on Tencents SmartQQ项目地址: https://gitcode.com/gh_mirrors/qq/qqbot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考