QQ 官方机器人配置指南

QQ 官方机器人 (QQ Bot) 完整配置教程，包含从创建机器人到接入 OpenClaw AI 的全过程，以及常见问题排查。

前置条件

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

配置步骤

步骤 1: 创建 QQ 机器人

1. 访问QQ 机器人平台
2. 点击「登录」，使用 QQ 扫码登录
3. 进入「开发者注册」页面，完成实名认证
4. 点击「创建机器人」，填写基本信息
5. 记录关键信息：
   • AppID (如: 102842119)
   • AppSecret (点击显示，只显示一次，务必保存！)

⚠️重要: AppSecret 只显示一次，立即保存！

步骤 2: 配置 IP 白名单

家庭宽带需要公网 IP，并配置到 QQ 开放平台。

获取公网 IP

curl https://api.ipify.org

配置白名单

1. 进入QQ 机器人控制台
2. 选择你的机器人
3. 点击「开发设置」→「IP 白名单」
4. 添加获取到的公网 IP
5. 保存

⚠️注意: 家庭宽带 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 已变更

解决方案:

1. 获取当前公网 IP:curl https://api.ipify.org
2. 登录QQ 机器人控制台
3. 更新 IP 白名单
4. 重启 QQ Bot

长期方案:

• 使用云服务器（固定 IP）
• 或使用内网穿透服务

问题 2: 无法收到消息

现象:

• Bot 已连接 WebSocket
• 心跳正常
• 但没有收到任何消息事件

原因 1: Intents 权限未开启

解决方案:

1. 登录QQ 机器人控制台
2. 进入「开发设置」→「权限设置」
3. 开启以下 Intents：
   • ✅ GUILDS (基础权限)
   • ✅ GROUP_AND_C2C_EVENT (私聊和群消息)
   • ✅ AT_MESSAGES (@消息)

Reason 2: Incorrect Event Subscription Method

Solution: Ensure that "Receive events using long connections" (WebSocket mode) is selected, rather than HTTP callbacks.

Reason 3: Bot Not Added as Friend/Not in Group

Solution:

• Private Chat: Add the bot as a QQ friend.
• Group Chat: Invite the bot to the group.

Issue 3: ModuleNotFoundError

Symptom:

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

Solution:

pip3 install requests aiohttp websockets --user

Issue 4: Authentication Successful but Unable to Receive Messages

Symptom:

✅ 鉴权成功!
Session ID: xxx
💓 心跳确认

But did not receiveC2C_MESSAGE_CREATEorAT_MESSAGE_CREATEevents.

Reason: Incorrect Intents value configuration

Solution: Use the correct Intents combination:

INTENTS = (1 << 0) | (1 << 25) | (1 << 30)
# GUILDS | GROUP_AND_C2C_EVENT | AT_MESSAGES

Issue 5: AI Response Timeout

Symptom:

⏳ 等待 OpenClaw AI 回复...
抱歉，AI 响应超时

原因: AI 处理器未运行或响应太慢

解决方案:

1. 确保 AI 处理器脚本在运行
2. 检查请求文件是否生成
3. 手动创建回复文件测试

文件结构

~/.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

调试技巧

1. 检查 WebSocket 连接

tail -f ~/.openclaw/workspace/qq_bot.log | grep -E "连接|心跳|收到"

2. 检查消息事件

tail -f ~/.openclaw/workspace/qq_bot.log | grep "收到事件"

3. 手动测试 AI 回复

# 创建测试请求
echo '{"request_id":"test","message":"你好"}' > ~/.openclaw/workspace/qq_queue/ai_request_test.json

# 创建回复
echo "你好！我是小皮" > ~/.openclaw/workspace/qq_queue/ai_response_test.txt

参考资料

• QQ 机器人平台文档
• QQ Bot API 文档
• Intents 说明

维护者: 小皮 🦊
版本: 1.0.0
更新时间: 2026-02-23