byzgpc
作者:byzgpc更新於 2026-05-18@clawhub_byzgpc/qqbot
指令碼工具

據 AlphaMoat 統計,截至 2026-10,qqbot 累計下載 13,334 次、獲 12 個星標,按累計下載量在本次參與排名的 10,914 個 AI 技能中排名第 2,091 位,在「開發程式設計」分類(1,069 個)中排名第 150 位。

列表預設按累計下載量排序,也可按星標排序;詳情頁排名按累計下載量計算。

累計下載
1.3萬
星標
12
全站下載量排名
#2,091
全站前 20% · 「開發程式設計」前 15%
平台累計下載星標評論
ClawHub ↗6113101
SkillHub ↗1.3萬12—

各平台的計數口徑不同,統計時間不一致。

這個技能是做什麼的

本指南涵蓋建立 QQ 機器人應用、立即保存僅顯示一次的 AppSecret、將伺服器的公網可連線 IP 加入平台白名單、設定 OpenClaw 及安裝 Python 模組。家用寬頻 IP 變更後必須同步更新白名單,否則可能無法取得 token。也列出權限、事件訂閱和收不到訊息等問題的排查步驟。

資料釋出於 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 原文

以下是作者釋出的原始檔案,按純文字顯示,本站未做修改或稽核;其中的連結不可點選,命令請核實後再執行。抓取於 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開發程式設計

程式設計專家 Pro:融合程式設計專家 2.0.3 工程專題與程式設計大神的鴻蒙 ArkTS/ArkUI、微信小程式和小遊戲開發資料。用於專案實現、根因除錯、審查、重構、測試、架構效能分析及多端開發驗證。支援自然語言和 @專題標識,按任務讀取包內知識;只問概念時直接回答。

↓ 104.7萬★ -user_814dbe54
程式設計專家 Pro開發程式設計

程式設計專家 Pro:融合程式設計專家 2.0.3 工程專題與程式設計大神的鴻蒙 ArkTS/ArkUI、微信小程式和小遊戲開發資料。用於專案實現、根因除錯、審查、重構、測試、架構效能分析及多端開發驗證。支援自然語言和 @專題標識,按任務讀取包內知識;只問概念時直接回答。

↓ 98.2萬★ 1user_28275a78
程式設計專家.Skill開發程式設計

程式設計專家.Skill P8級程式設計助手,25年實戰經驗技能Skill,全棧:Java/Php網站/軟體專案、API設計、Bug診斷、程式碼生成、程式碼審查、重構、測試用例、效能基準、技術選型、文件生成、任務拆解、Spec驅動、Karpathy規範、CMS二次開發、前端設計、MySQL/Mariadb、專案知識圖譜,以及工程紀律層(根因除錯硬閉環、階段導航、事故復盤/SLO、威脅建模/供應鏈安全、生產就緒/漸進式釋出、AI編碼治理、面向Agent程式碼可讀性、LLM應用安全)。支援 @標識 顯式呼叫跳過路由。

↓ 70.1萬★ 6user_613b33ea
Github開發程式設計

用 gh 命令列工具檢視 GitHub 上的 PR 檢查、工作流執行與 API 查詢的技能。

↓ 48萬★ 714Peter Steinberger

資料月份:2026-10 · 下載/星標數聚合自公開技能註冊庫(ClawHub、SkillHub),按月更新。口徑說明見資料方法。