如何快速搭建QQBot：基于SmartQQ协议的终极Python聊天机器人指南 🚀

QQBot是一个用Python实现的、基于腾讯SmartQQ协议的QQ机器人，可运行在Linux、Windows和Mac OSX平台下。通过扩展QQBot，你可以轻松实现监控QQ消息、自动推送通知、搭建智能聊天机器人等实用功能，让日常沟通和信息管理更高效。

📌 什么是QQBot？核心功能解析

QQBot作为一款轻量级聊天机器人框架，凭借Python的简洁语法和强大生态，为开发者提供了灵活的扩展能力。无论是个人用户用于消息提醒，还是企业团队构建自动化沟通工具，QQBot都能满足需求。

QQBot核心架构示意图，展示了消息处理、插件系统和协议交互的关键模块

✨ 为什么选择QQBot？

• 跨平台兼容：无缝运行在Linux、Windows和macOS系统
• 插件化设计：通过简单的Python脚本即可扩展功能
• 多模式登录：支持GUI、邮箱、服务器和文本四种二维码显示模式
• 丰富接口：提供9个核心API接口，满足消息收发、联系人管理等需求

🚀 零基础安装：3步快速启动QQBot

1️⃣ 环境准备

确保你的系统已安装Python 2.7/3.4+环境，推荐使用Python 3.6以上版本获得更好兼容性。

2️⃣ 一键安装命令

通过pip工具快速安装QQBot：

pip install qqbot

或从源码仓库克隆安装：

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

3️⃣ 首次启动与登录

在命令行输入以下命令启动QQBot：

qqbot

首次启动会自动弹出二维码图片，使用手机QQ扫码授权即可登录。登录信息将保存在本地，下次启动可直接使用：

qqbot -q 你的QQ号码

QQBot登录流程示意图，展示了扫码授权到消息接收的完整链路

💻 核心操作指南：5分钟上手QQBot命令

🔍 联系人管理命令

# 列出所有好友
qq list buddy

# 搜索名称含"李"的好友
qq list buddy :like:李

# 查看群"456班"成员
qq list group-member 456班

📩 消息发送功能

# 给好友"jack"发送消息
qq send buddy jack 你好，我是QQBot！

# 给群"技术交流群"发送表情消息
qq send group 技术交流群 /微笑 欢迎加入！

🔌 插件管理

# 加载聊天机器人插件
qq plug sample

# 查看已加载插件
qq plugins

🛠️ 插件开发实战：打造你的专属机器人

基础消息响应插件

创建sample.py文件，实现简单的消息交互：

def onQQMessage(bot, contact, member, content):
    if content == '-hello':
        bot.SendTo(contact, '你好！我是QQBot机器人')
    elif content == '-time':
        import time
        bot.SendTo(contact, f'当前时间：{time.ctime()}')
    elif '@ME' in content:
        bot.SendTo(contact, f'{member.name} 你@我有事吗？')

将文件保存到~/.qqbot-tmp/plugins/目录，通过qq plug sample命令加载，即可实现：

• 收到-hello回复问候语
• 收到-time返回当前时间
• 被@时自动回应

⏰ 定时任务插件

使用qqbotsched装饰器创建定时任务：

from qqbot import qqbotsched

@qqbotsched(hour='8,18', minute='0')
def daily_reminder(bot):
    # 每天8:00和18:00发送提醒
    gl = bot.List('group', '工作群')
    if gl:
        for group in gl:
            bot.SendTo(group, '📢 工作时间提醒：保持专注，高效工作！')

⚙️ 高级配置：QQBot个性化设置

配置文件详解

QQBot的核心配置文件位于~/.qqbot-tmp/v2.x.conf，可自定义：

• termServerPort：API服务器端口（默认8188）
• mailAccount：邮箱模式接收二维码
• cmdQrcode：终端文本模式显示二维码
• pluginPath：自定义插件目录

多账号同时运行

通过指定不同端口实现多账号登录：

# 账号1：使用默认端口
qqbot -u user1

# 账号2：指定端口8189
qqbot -u user2 --termServerPort 8189

❓ 常见问题与解决方案

🔒 登录相关问题

• 无法弹出二维码：使用--cmdQrcode参数启用文本模式
• 登录信息过期：配置restartOnOffline: True实现自动重启
• 服务器无GUI：设置邮箱模式接收二维码图片

📝 功能限制说明

由于SmartQQ协议限制，目前存在以下已知限制：

• 登录状态有效期为1-2天，需定期重新扫码
• 暂不支持发送图片、文件等富媒体消息
• 无法获取联系人的完整QQ号码

📚 资源与扩展

官方插件推荐

• schedrestart：定时重启功能（默认加载）
• miniirc：IRC服务器模式，支持命令行聊天
• passwordlogin：用户名密码登录插件（实验性）

学习资源

• 完整API文档：qqbot/qqbotcls.py
• 表情代码映射：qqbot/facemap.py
• 回调函数示例：qqbot/plugins/sampleslots.py

📌 注意事项

重要提示：腾讯SmartQQ服务已于2019年1月3日停止服务，本项目目前已无法使用，不再更新和维护。本文档仅供学习参考QQBot的架构设计和Python机器人开发思路。

通过本指南，你已经掌握了QQBot的安装配置、核心命令和插件开发方法。这款强大的Python机器人框架不仅能帮助你自动化日常沟通，更能作为学习Python网络编程和协议解析的优秀实践案例。开始你的机器人开发之旅吧！ 🤖