by 运行时依赖
安装命令
点击复制技能文档
QQ 官方机器人配置指南 QQ 官方机器人（QQ Bot）完整配置教程，包含从创建机器人到接入 OpenClaw AI 的全过程，以及常见问题排查。
前置条件 QQ 号（建议使用小号） 可访问公网 IP（家庭宽带需处理动态 IP） 服务器或本地机器 OpenClaw 已安装
配置步骤 步骤 1: 创建 QQ 机器人 访问 QQ 机器人平台 点击「登录」，使用 QQ 扫码登录 进入「开发者注册」页面，完成实名认证 点击「创建机器人」，填写基本信息 记录关键信息：AppID（如：102842119）和 AppSecret（点击显示，只显示一次，务必保存！） 重要：AppSecret 只显示一次，立即保存！
步骤 2: 配置 IP 白名单 家庭宽带需要公网 IP，并配置到 QQ 开放平台。 获取公网 IP：curl https://api.ipify.org 配置白名单 进入 QQ 机器人控制台 选择你的机器人 点击「开发设置」→「IP 白名单」 添加获取到的公网 IP 保存 注意：家庭宽带 IP 会定期变化，需要及时更新白名单，否则会出现错误 11298。
步骤 3: 配置 OpenClaw 在 openclaw.json 中添加 QQ 频道配置： { "channels": { "qq": { "enabled": true, "appId": "你的AppID", "appSecret": "你的AppSecret" } } }
步骤 4: 部署 QQ Bot 程序 复制 qq_official_bot.py 到工作区：cp qq_official_bot.py ~/.openclaw/workspace/ 编辑配置文件：APP_ID = "你的AppID" 和 APP_SECRET = "你的AppSecret"
步骤 5: 启动机器人 启动 QQ Bot：~/.openclaw/workspace/qq_bot_daemon.sh start 查看状态：~/.openclaw/workspace/qq_bot_daemon.sh status 查看日志：tail -f ~/.openclaw/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 回复超时 现象：等待 OpenClaw AI 回复... 抱歉，AI 响应超时 原因：AI 处理器未运行或响应太慢 解决方案：确保 AI 处理器脚本在运行，检查请求文件是否生成，手动创建回复文件测试。
文件结构 ~/.openclaw/workspace/ ├── qq_official_bot.py # QQ Bot 主程序 ├── qq_bot_daemon.sh # 启动管理脚本 ├── qq_bot.log # 运行日志 ├── qq_queue/ # 消息队列目录 │ ├── ai_request_.json # AI 请求 │ └── ai_response_.txt # AI 回复 └── qq_ai_handler.sh # AI 处理器
管理命令 启动：~/.openclaw/workspace/qq_bot_daemon.sh start 停止：~/.openclaw/workspace/qq_bot_daemon.sh stop 重启：~/.openclaw/workspace/qq_bot_daemon.sh restart 查看状态：~/.openclaw/workspace/qq_bot_daemon.sh status 查看日志：tail -f ~/.openclaw/workspace/qq_bot.log
调试技巧
- 检查 WebSocket 连接：tail -f ~/.openclaw/workspace/qq_bot.log | grep -E "连接|心跳|收到"
- 检查消息事件：tail -f ~/.openclaw/workspace/qq_bot.log | grep "收到事件"
- 手动测试 AI 回复：创建测试请求和回复文件。
参考资料 QQ 机器人平台文档 QQ Bot API 文档 Intents 说明
维护者：小皮 🦊 版本：1.0.0 更新时间：2026-02-23