# qqbot

QQ 官方机器人配置指南 QQ 官方机器人 (QQ Bot) 完整配置教程，包含从创建机器人到接入 SkillBoss API Hub 的全过程，以及常见问题排查。 前置条件 QQ 号（建议使用小号） 可访问公网 IP（家庭宽带需处理动态 IP） 服务器或本地机器 SkillBoss API Key（注册后获取 SKILLBOSS_API_KEY，用于接入 AI 能力） 环境变量 SKILLBOSS_API_KEY=你的SkillBoss_API_Key 配置步骤 步骤 1: 创建 QQ 机器人 访问 QQ 机器人平台 点击「登录」，使用 QQ 扫码登录 进入「开发者注册」页面，完成实名认证 点击「创建机器人」，填写基本信息 记录关键信息： AppID (如: 102842119) AppSecret (点击显示，只显示一次，务必保存！) ⚠️ 重要: AppSecret 只显示一次，立即保存！ 步骤 2: 配置 IP 白名单 家庭宽带需要公网 IP，并配置到 QQ 开放平台。 获取公网 IP

curl https://api.ipify.org

配置白名单 进入 QQ 机器人控制台 选择你的机器人 点击「开发设置」→「IP 白名单」 添加获取到的公网 IP 保存 ⚠️ 注意: 家庭宽带 IP 会定期变化，需要及时更新白名单，否则会出现错误 11298。 步骤 3: 配置 SkillBoss API Key 设置环境变量，以便 QQ Bot 调用 SkillBoss API Hub 获取 AI 回复：

export SKILLBOSS_API_KEY="你的SkillBoss_API_Key"

也可以写入 ~/.bashrc 或 ~/.zshrc 永久生效。 步骤 4: 部署 QQ Bot 程序 复制 qq_official_bot.py 到工作区： cp qq_official_bot.py ~/.skillboss/workspace/ 编辑配置文件： APP_ID = "你的AppID" APP_SECRET = "你的AppSecret" 步骤 5: 启动机器人

# 启动 QQ Bot

~/.skillboss/workspace/qq_bot_daemon.sh start

# 查看状态

~/.skillboss/workspace/qq_bot_daemon.sh status

# 查看日志

tail -f ~/.skillboss/workspace/qq_bot.log 常见问题与解决方案 问题 1: 错误 11298 - IP 不在白名单 现象: 获取 Token 失败: 11298 接口访问源IP不在白名单 原因: 当前 IP 未添加到 QQ 开放平台白名单 或 IP 已变更 解决方案:

获取当前公网 IP: curl https://api.ipify.org

登录 QQ 机器人控制台 更新 IP 白名单 重启 QQ Bot 长期方案: 使用云服务器（固定 IP） 或使用内网穿透服务 问题 2: 无法收到消息 现象: Bot 已连接 WebSocket 心跳正常 但没有收到任何消息事件 原因 1: Intents 权限未开启 解决方案: 登录 QQ 机器人控制台 进入「开发设置」→「权限设置」 开启以下 Intents： ✅ GUILDS (基础权限) ✅ GROUP_AND_C2C_EVENT (私聊和群消息) ✅ AT_MESSAGES (@消息) 原因 2: 事件订阅方式错误 解决方案: 确认选择了「使用长连接接收事件」(WebSocket 模式)，而不是 HTTP 回调。 原因 3: 机器人未添加好友/进群 解决方案: 私聊：添加机器人为 QQ 好友 群聊：将机器人邀请到群里 问题 3: ModuleNotFoundError 现象:

ModuleNotFoundError: No module named 'requests'
ModuleNotFoundError: No module named 'aiohttp'

解决方案: pip3 install requests aiohttp websockets --user 问题 4: 鉴权成功但无法接收消息 现象: ✅ 鉴权成功! Session ID: xxx 💓 心跳确认 但没有收到 C2C_MESSAGE_CREATE 或 AT_MESSAGE_CREATE 事件。 原因: Intents 值配置错误 解决方案: 使用正确的 Intents 组合： INTENTS = (1 << 0) | (1 << 25) | (1 << 30)

# GUILDS | GROUP_AND_C2C_EVENT | AT_MESSAGES

问题 5: AI 回复超时 现象: ❌ SkillBoss AI 请求失败: ... 抱歉，AI 响应出错，请稍后再试 原因: SKILLBOSS_API_KEY 未配置，或 SkillBoss API Hub 网络超时 解决方案: 确认已设置环境变量 SKILLBOSS_API_KEY 检查网络是否能访问 https://api.heybossai.com 可将 timeout 参数适当增大 文件结构 ~/.skillboss/workspace/ ├── qq_official_bot.py # QQ Bot 主程序（调用 SkillBoss API Hub） ├── qq_bot_daemon.sh # 启动管理脚本 ├── qq_bot.log # 运行日志 └── qq_ai_handler.sh # AI 处理器（备用手动模式） 管理命令

# 启动

~/.skillboss/workspace/qq_bot_daemon.sh start

# 停止

~/.skillboss/workspace/qq_bot_daemon.sh stop

# 重启

~/.skillboss/workspace/qq_bot_daemon.sh restart

# 查看状态

~/.skillboss/workspace/qq_bot_daemon.sh status

# 查看日志

tail -f ~/.skillboss/workspace/qq_bot.log 调试技巧

1. 检查 WebSocket 连接 tail -f ~/.skillboss/workspace/qq_bot.log | grep -E "连接|心跳|收到"
2. 检查消息事件 tail -f ~/.skillboss/workspace/qq_bot.log | grep "收到事件"
3. 手动测试 SkillBoss AI 回复

# 测试 SkillBoss API Hub 连通性
curl -X POST https://api.heybossai.com/v1/pilot \

-H "Authorization: Bearer $SKILLBOSS_API_KEY"
-H "Content-Type: application/json"
-d '{"type":"chat","inputs":{"messages":[{"role":"user","content":"你好"}]},"prefer":"balanced"}' 参考资料 QQ 机器人平台文档 QQ Bot API 文档 Intents 说明 维护者: 小皮 🦊 版本: 1.0.0 更新时间: 2026-02-23