byzgpc

qqbot

開発v1.0.0
作者:byzgpc更新日 2026-05-18@clawhub_byzgpc/qqbot
スクリプトツール

AlphaMoatによると、2026-10時点でqqbotのダウンロード数は13,334、スター数は12で、累計ダウンロード数で今回のランキング対象AIスキル10,914件中2,091位、開発では1,069件中150位です。

一覧の初期表示は累計ダウンロード数順で、スター数順にも並べ替えできます。詳細ページの順位は累計ダウンロード数で計算しています。

ダウンロード数
1.3万
スター数
12
累計ダウンロード順位
#2,091
全体の上位 20% · 開発の上位 15%
プラットフォームダウンロード数スター数コメント
ClawHub ↗6113101
SkillHub ↗1.3万12—

プラットフォームごとに集計方法と集計時点が異なります。

このスキルでできること

QQ ボットアプリの作成、一度だけ表示される AppSecret の保存、公開到達可能なサーバー IP のプラットフォーム許可リストへの登録、OpenClaw の設定、Python モジュールの導入を案内します。自宅の IP が変わった場合は許可リストも更新しないと、トークン取得に失敗することがあります。権限、イベント購読、メッセージ受信の確認項目も扱います。

資料公開日 2026-10-27

できること

  • QQ ボットを自分の agent につなぐところから始める
  • 接続後にトークンが取れない問題を切り分ける

使う場面

  • OpenClaw 用 QQ ボットを設定するとき
  • 認証やメッセージ受信の問題を調べるとき

プロンプト例

スキルのドキュメントをもとに生成した例であり、実際の実行結果ではありません。

QQ ボットを接続する手順を順に教えてください
トークン取得に失敗します。設定のどこが違うか見てください

月次の推移

ダウンロード数1.3万
358688211.4万2026-03 · ダウンロード数 43082026-05 · ダウンロード数 55582026-07 · ダウンロード数 61992026-08 · ダウンロード数 64502026-09 · ダウンロード数 72312026-10 · ダウンロード数 1.3万26-0326-0926-10
スター数12
1112122026-03 · スター数 112026-05 · スター数 122026-07 · スター数 122026-08 · スター数 122026-09 · スター数 122026-10 · スター数 1226-0326-0926-10

2026-09 から集計方法を変更し、同名スキルを作者ごとに分けて集計し、全スキルを対象にしました。破線は変更前の月で、変更後のデータとは直接比較せず、変更をまたぐ増減も計算していません。

月ダウンロード数前月比スター数
2026-101.3万—12
2026-097231—12
2026-086450+4.0%12
2026-076199—12
2026-055558—12
2026-034308—11

SKILL.md 原文

作者が公開した元のファイルをテキストのまま表示しています。AlphaMoat による編集や審査はしていません。リンクはクリックできません。コマンドは内容を確認してから実行してください。取得日 2026-10-23。

5.5 KB・ClawHub v1.0.0
# QQ 官方机器人配置指南

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

## 前置条件

- QQ 号(建议使用小号)
- 可访问公网 IP(家庭宽带需处理动态 IP)
- 服务器或本地机器
- OpenClaw 已安装
すべて表示(全 284 行)

---

## 配置步骤

### 步骤 1: 创建 QQ 机器人

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

⚠️ **重要**: AppSecret 只显示一次,立即保存!

---

### 步骤 2: 配置 IP 白名单

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

#### 获取公网 IP

```bash
curl https://api.ipify.org
```

#### 配置白名单

1. 进入 [QQ 机器人控制台](https://bot.q.qq.com/console/)
2. 选择你的机器人
3. 点击「开发设置」→「IP 白名单」
4. 添加获取到的公网 IP
5. 保存

⚠️ **注意**: 家庭宽带 IP 会定期变化,需要及时更新白名单,否则会出现错误 11298。

---

### 步骤 3: 配置 OpenClaw

在 `openclaw.json` 中添加 QQ 频道配置:

```json
{
  "channels": {
    "qq": {
      "enabled": true,
      "appId": "你的AppID",
      "appSecret": "你的AppSecret"
    }
  }
}
```

---

### 步骤 4: 部署 QQ Bot 程序

复制 `qq_official_bot.py` 到工作区:

```bash
cp qq_official_bot.py ~/.openclaw/workspace/
```

编辑配置文件:

```python
APP_ID = "你的AppID"
APP_SECRET = "你的AppSecret"
```

---

### 步骤 5: 启动机器人

```bash
# 启动 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 机器人控制台](https://bot.q.qq.com/console/)
3. 更新 IP 白名单
4. 重启 QQ Bot

**长期方案**:
- 使用云服务器(固定 IP)
- 或使用内网穿透服务

---

### 问题 2: 无法收到消息

**现象**: 
- Bot 已连接 WebSocket
- 心跳正常
- 但没有收到任何消息事件

**原因 1: Intents 权限未开启**

**解决方案**:
1. 登录 [QQ 机器人控制台](https://bot.q.qq.com/console/)
2. 进入「开发设置」→「权限设置」
3. 开启以下 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'
```

**解决方案**:
```bash
pip3 install requests aiohttp websockets --user
```

---

### 问题 4: 鉴权成功但无法接收消息

**现象**:
```
✅ 鉴权成功!
Session ID: xxx
💓 心跳确认
```
但没有收到 `C2C_MESSAGE_CREATE` 或 `AT_MESSAGE_CREATE` 事件。

**原因**: Intents 值配置错误

**解决方案**:
使用正确的 Intents 组合:
```python
INTENTS = (1 << 0) | (1 << 25) | (1 << 30)
# GUILDS | GROUP_AND_C2C_EVENT | AT_MESSAGES
```

---

### 问题 5: AI 回复超时

**现象**:
```
⏳ 等待 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 处理器
```

---

## 管理命令

```bash
# 启动
~/.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 连接

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

### 2. 检查消息事件

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

### 3. 手动测试 AI 回复

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

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

---

## 参考资料

- [QQ 机器人平台文档](https://bot.q.qq.com/wiki)
- [QQ Bot API 文档](https://bot.q.qq.com/wiki/develop/api/)
- [Intents 说明](https://bot.q.qq.com/wiki/develop/api/gateway/intents.html)

---

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

開発の人気スキル

编程大神.Skill開発

【全栈能力】编程大神.Skill:面向复杂真实项目的高阶全栈编程助手。不止生成代码,而是从一句目标接手陌生代码库,拆解需求、补齐实现、追到根因、完成重构、联调前后端,并把结果推进到能运行、能验证、能交付。覆盖 Web、后端、脚本、iOS、安卓、鸿蒙 ArkUI、微信小程序及其他技术栈,支持中英文工程、疑难 Bug、跨模块任务和长任务续做;用构建、日志、真实入口、设备或接口证据说明结果。仅问概念时直接回答,要求落地时持续推进到验收或明确阻塞。

↓ 1125.9万★ 82u_42bbb65f
编程专家Pro.Skill開発

编程专家 Pro:融合编程专家 2.0.3 工程专题与编程大神的鸿蒙 ArkTS/ArkUI、微信小程序和小游戏开发资料。用于项目实现、根因调试、审查、重构、测试、架构性能分析及多端开发验证。支持自然语言和 @专题标识,按任务读取包内知识;只问概念时直接回答。

↓ 626.9万★ 32user_47d655f0
编程专家.Skill開発

编程专家.Skill P8级编程助手,25年实战经验技能Skill,全栈:Java/Php网站/软件项目、API设计、Bug诊断、代码生成、代码审查、重构、测试用例、性能基准、技术选型、文档生成、任务拆解、Spec驱动、Karpathy规范、CMS二次开发、前端设计、MySQL/Mariadb、项目知识图谱,以及工程纪律层(根因调试硬闭环、阶段导航、事故复盘/SLO、威胁建模/供应链安全、生产就绪/渐进式发布、AI编码治理、面向Agent代码可读性、LLM应用安全)。支持 @标识 显式调用跳过路由。

↓ 600.7万★ 378user_741dc82b
dev-expert開発

编程专家.Skill P8级编程助手,25年实战经验技能Skill,全栈:Java/Php网站/软件项目、API设计、Bug诊断、代码生成、代码审查、重构、测试用例、性能基准、技术选型、文档生成、任务拆解、Spec驱动、Karpathy规范、CMS二次开发、前端设计、MySQL/Mariadb、项目知识图谱,以及工程纪律层(根因调试硬闭环、阶段导航、事故复盘/SLO、威胁建模/供应链安全、生产就绪/渐进式发布、AI编码治理、面向Agent代码可读性、LLM应用安全)。支持 @标识 显式调用跳过路由。

↓ 528.1万★ 32user_814dbe54
dev-expert-pro開発

工程专题、鸿蒙与微信小程序开发的集成派生版

↓ 104.7万★ -user_814dbe54
编程专家 Pro開発

编程专家 Pro:融合编程专家 2.0.3 工程专题与编程大神的鸿蒙 ArkTS/ArkUI、微信小程序和小游戏开发资料。用于项目实现、根因调试、审查、重构、测试、架构性能分析及多端开发验证。支持自然语言和 @专题标识,按任务读取包内知识;只问概念时直接回答。

↓ 98.2万★ 1user_28275a78
编程专家.Skill開発

适用场景:全栈编程助手。接到需求先读现有代码和约束,再动手:Java/PHP 开发、接口设计、缺陷定位、代码评审、重构、测试用例、性能排查、技术选型与文档产出,也做 CMS 二次开发、前端页面和 MySQL 调优。每次改动先给方案和影响范围,改完必须跑验证,交付附交接说明。适合要把代码真正跑通、而不是只要片段的场景。写完代码常要配套的造价、法律、工程文档,站内已有现成技能,用「查找技能」按需求找即可。

↓ 70.1万★ 6user_613b33ea
Github開発

gh コマンドラインで GitHub の PR チェック、ワークフロー実行、API 照会を扱うスキルです。

↓ 48万★ 714Peter Steinberger

データ月:2026-10 · ダウンロード数とスター数は公開スキルレジストリ(ClawHub、SkillHub)から月単位で集計しています。詳しくはデータの方法論をご覧ください。