前置条件 QQ 号（建议使用小号） 可访问公网 IP（家庭宽带需处理动态 IP） 服务器或本地机器 OpenClaw

否则会出现错误 11298，使用 QQ 扫码登录 进入「开发者注册」页面， 获取公网 IP curl https://api.ipify.org 配置白名单 进入 QQ 机器人控制台 选择你的机器人 点击「开发设置」→「IP 白名单」 添加获取到的公网 IP 保存 ⚠️ 注意 : 家庭宽带 IP 会定期变化， QQ 官方机器人配置指南 QQ 官方机器人 (QQ Bot) 完整配置教程，而不是 HTTP 回调，完成实名认证 点击「创建机器人」，appSecret: 你的AppSecret} }} 步骤 4: 部署 QQ Bot 程序 复制 qq_official_bot.py 到工作区： Shell cp qq_official_bot.py ~/.openclaw/workspace/ 编辑配置文件： Python APP_ID = 你的AppIDAPP_SECRET = 你的AppSecret 步骤 5: 启动机器人 Shell # 启动 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 不在白名单 现象 : Plaintext 获取 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 模式)， 步骤 3: 配置 OpenClaw 在 openclaw.json 中添加 QQ 频道配置： JSON { channels: {qq: {enabled: true， 原因 3: 机器人未添加好友 / 进群 解决方案 : 私聊：添加机器人为 QQ 好友 群聊：将机器人邀请到群里 问题 3: ModuleNotFoundError 现象 : Plaintext ModuleNotFoundError: No module named requestsModuleNotFoundError: No module named aiohttp 解决方案 : Shell pip3 install requests aiohttp websockets --user 问题 4: 鉴权成功但无法接收消息 现象 : Plaintext ✅ 鉴权成功!Session ID: xxx，需要及时更新白名单，appId: 你的AppID，包含从创建机器人到接入 OpenClaw AI 的全过程， 前置条件 QQ 号（建议使用小号） 可访问公网 IP（家庭宽带需处理动态 IP） 服务器或本地机器 OpenClaw 已安装 配置步骤步骤 1: 创建 QQ 机器人 访问 QQ 机器人平台 点击「登录」，立即保存！ 步骤 2: 配置 IP 白名单 家庭宽带需要公网 IP，并配置到 QQ 开放平台，以及常见问题排查，填写基本信息 记录关键信息： ⚠️ 重要 : AppSecret 只显示一次，。