Qqbot

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

# QQ 官方机器人 Skill

📦 包含完整配置步骤、IP 白名单管理、故障排除

## 快速开始

1. 阅读 `SKILL.md` 获取完整指南
2. 复制 `config.example.json` 为 `qq_official_bot_config.json` 并填入配置
3. 运行 `qq_bot_daemon.sh start` 启动机器人

## 核心文件

| 文件 | 说明 |
|------|------|
| `SKILL.md` | 完整文档和故障排除 |
| `qq_official_bot.py` | QQ Bot 主程序 |
| `qq_bot_daemon.sh` | 启动管理脚本 |
| `qq_ai_handler.sh` | AI 处理器脚本 |
| `config.example.json` | 配置模板 |

## 快速命令

```bash
# 启动
./qq_bot_daemon.sh start

# 停止
./qq_bot_daemon.sh stop

# 重启
./qq_bot_daemon.sh restart

# 查看状态
./qq_bot_daemon.sh status
```

---

**维护者**: 小皮 🦊
**版本**: 1.0.0