據 AlphaMoat 統計,截至 2026-10,qqbot 累計下載 13,334 次、獲 12 個星標,按累計下載量在本次參與排名的 10,914 個 AI 技能中排名第 2,091 位,在「開發程式設計」分類(1,069 個)中排名第 150 位。
列表預設按累計下載量排序,也可按星標排序;詳情頁排名按累計下載量計算。
| 平台 | 累計下載 | 星標 | 評論 |
|---|---|---|---|
| ClawHub ↗ | 6113 | 10 | 1 |
| SkillHub ↗ | 1.3萬 | 12 | — |
各平台的計數口徑不同,統計時間不一致。
本指南涵蓋建立 QQ 機器人應用、立即保存僅顯示一次的 AppSecret、將伺服器的公網可連線 IP 加入平台白名單、設定 OpenClaw 及安裝 Python 模組。家用寬頻 IP 變更後必須同步更新白名單,否則可能無法取得 token。也列出權限、事件訂閱和收不到訊息等問題的排查步驟。
資料釋出於 2026-10-27
以下是根據技能文件生成的示例,不代表實際執行結果。
2026-09 起統計方法調整:同名技能按作者分別統計,並覆蓋全部技能。圖中虛線為調整前的月份,與之後的資料不直接比較,也不計算跨越調整的增長。
| 月份 | 累計下載 | 環比 | 星標 |
|---|---|---|---|
| 2026-10 | 1.3萬 | — | 12 |
| 2026-09 | 7231 | — | 12 |
| 2026-08 | 6450 | +4.0% | 12 |
| 2026-07 | 6199 | — | 12 |
| 2026-05 | 5558 | — | 12 |
| 2026-03 | 4308 | — | 11 |
以下是作者釋出的原始檔案,按純文字顯示,本站未做修改或稽核;其中的連結不可點選,命令請核實後再執行。抓取於 2026-10-23。
# QQ 官方机器人配置指南 QQ 官方机器人 (QQ Bot) 完整配置教程,包含从创建机器人到接入 OpenClaw AI 的全过程,以及常见问题排查。 ## 前置条件 - QQ 号(建议使用小号) - 可访问公网 IP(家庭宽带需处理动态 IP) - 服务器或本地机器 - OpenClaw 已安装
---
## 配置步骤
### 步骤 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:面向複雜真實專案的高階全棧程式設計助手。不止生成程式碼,而是從一句目標接手陌生程式碼庫,拆解需求、補齊實現、追到根因、完成重構、聯調前後端,並把結果推進到能執行、能驗證、能交付。覆蓋 Web、後端、指令碼、iOS、安卓、鴻蒙 ArkUI、微信小程式及其他技術棧,支援中英文工程、疑難 Bug、跨模組任務和長任務續做;用構建、日誌、真實入口、裝置或介面證據說明結果。僅問概念時直接回答,要求落地時持續推進到驗收或明確阻塞。
程式設計專家 Pro:融合程式設計專家 2.0.3 工程專題與程式設計大神的鴻蒙 ArkTS/ArkUI、微信小程式和小遊戲開發資料。用於專案實現、根因除錯、審查、重構、測試、架構效能分析及多端開發驗證。支援自然語言和 @專題標識,按任務讀取包內知識;只問概念時直接回答。
程式設計專家.Skill P8級程式設計助手,25年實戰經驗技能Skill,全棧:Java/Php網站/軟體專案、API設計、Bug診斷、程式碼生成、程式碼審查、重構、測試用例、效能基準、技術選型、文件生成、任務拆解、Spec驅動、Karpathy規範、CMS二次開發、前端設計、MySQL/Mariadb、專案知識圖譜,以及工程紀律層(根因除錯硬閉環、階段導航、事故復盤/SLO、威脅建模/供應鏈安全、生產就緒/漸進式釋出、AI編碼治理、面向Agent程式碼可讀性、LLM應用安全)。支援 @標識 顯式呼叫跳過路由。
程式設計專家.Skill P8級程式設計助手,25年實戰經驗技能Skill,全棧:Java/Php網站/軟體專案、API設計、Bug診斷、程式碼生成、程式碼審查、重構、測試用例、效能基準、技術選型、文件生成、任務拆解、Spec驅動、Karpathy規範、CMS二次開發、前端設計、MySQL/Mariadb、專案知識圖譜,以及工程紀律層(根因除錯硬閉環、階段導航、事故復盤/SLO、威脅建模/供應鏈安全、生產就緒/漸進式釋出、AI編碼治理、面向Agent程式碼可讀性、LLM應用安全)。支援 @標識 顯式呼叫跳過路由。
程式設計專家 Pro:融合程式設計專家 2.0.3 工程專題與程式設計大神的鴻蒙 ArkTS/ArkUI、微信小程式和小遊戲開發資料。用於專案實現、根因除錯、審查、重構、測試、架構效能分析及多端開發驗證。支援自然語言和 @專題標識,按任務讀取包內知識;只問概念時直接回答。
程式設計專家 Pro:融合程式設計專家 2.0.3 工程專題與程式設計大神的鴻蒙 ArkTS/ArkUI、微信小程式和小遊戲開發資料。用於專案實現、根因除錯、審查、重構、測試、架構效能分析及多端開發驗證。支援自然語言和 @專題標識,按任務讀取包內知識;只問概念時直接回答。
程式設計專家.Skill P8級程式設計助手,25年實戰經驗技能Skill,全棧:Java/Php網站/軟體專案、API設計、Bug診斷、程式碼生成、程式碼審查、重構、測試用例、效能基準、技術選型、文件生成、任務拆解、Spec驅動、Karpathy規範、CMS二次開發、前端設計、MySQL/Mariadb、專案知識圖譜,以及工程紀律層(根因除錯硬閉環、階段導航、事故復盤/SLO、威脅建模/供應鏈安全、生產就緒/漸進式釋出、AI編碼治理、面向Agent程式碼可讀性、LLM應用安全)。支援 @標識 顯式呼叫跳過路由。
用 gh 命令列工具檢視 GitHub 上的 PR 檢查、工作流執行與 API 查詢的技能。
資料月份:2026-10 · 下載/星標數聚合自公開技能註冊庫(ClawHub、SkillHub),按月更新。口徑說明見資料方法。