# Send qqbot to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "qqbot",
    "name": "qqbot",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/byzgpc/qqbot",
    "canonicalUrl": "https://clawhub.ai/byzgpc/qqbot",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/qqbot",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=qqbot",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "publish-interactive.sh",
      "_meta.json",
      "publish-clawhub.js",
      "clawhub-publish-v2.js",
      "clawhub-publish.js",
      "STEP_BY_STEP_GUIDE.txt"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "qqbot",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-05T03:20:19.459Z",
      "expiresAt": "2026-05-12T03:20:19.459Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=qqbot",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=qqbot",
        "contentDisposition": "attachment; filename=\"qqbot-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "qqbot"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/qqbot"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/qqbot",
    "downloadUrl": "https://openagent3.xyz/downloads/qqbot",
    "agentUrl": "https://openagent3.xyz/skills/qqbot/agent",
    "manifestUrl": "https://openagent3.xyz/skills/qqbot/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/qqbot/agent.md"
  }
}
```
## Documentation

### 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

### 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
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: byzgpc
- Version: 1.0.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-05T03:20:19.459Z
- Expires at: 2026-05-12T03:20:19.459Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/qqbot)
- [Send to Agent page](https://openagent3.xyz/skills/qqbot/agent)
- [JSON manifest](https://openagent3.xyz/skills/qqbot/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/qqbot/agent.md)
- [Download page](https://openagent3.xyz/downloads/qqbot)