268 lines
5.8 KiB
Markdown
268 lines
5.8 KiB
Markdown
<div align="center">
|
||
|
||
# QQ Bot Channel Plugin for Moltbot
|
||
|
||
QQ 开放平台 Bot API 的 Moltbot 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。
|
||
|
||
[](https://www.npmjs.com/package/@sliverp/qqbot)
|
||
[](./LICENSE)
|
||
[](https://bot.q.qq.com/wiki/)
|
||
[](https://github.com/sliverp/moltbot)
|
||
[](https://nodejs.org/)
|
||
[](https://www.typescriptlang.org/)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## ⭐ Star 趋势
|
||
|
||
<!-- 在这里放置 Star 数量变化图 -->
|
||
|
||
---
|
||
|
||
## 📸 使用示例
|
||
|
||
<img width="600" alt="使用示例" src="https://github.com/user-attachments/assets/6f1704ab-584b-497e-8937-96f84ce2958f" />
|
||
|
||
---
|
||
|
||
## ✨ 功能特性
|
||
|
||
- 🔒 **多场景支持** - C2C 私聊、群聊 @消息、频道消息、频道私信
|
||
- 🖼️ **富媒体消息** - 支持图片收发、文件发送
|
||
- ⏰ **定时推送** - 支持定时任务到时后主动推送
|
||
- 🔗 **URL 无限制** - 私聊可直接发送 URL
|
||
- ⌨️ **输入状态** - Bot 正在输入中状态提示
|
||
- 🔄 **热更新** - 支持 npm 方式安装和热更新
|
||
- 📝 **Markdown** - 支持 Markdown 格式（即将更新）
|
||
|
||
---
|
||
|
||
## 📦 安装
|
||
|
||
### 方式一：腾讯云 Lighthouse 镜像（最简单）
|
||
|
||
[](https://cloud.tencent.com/product/lighthouse)
|
||
|
||
直接使用预装好的腾讯云 Lighthouse 镜像，开箱即用，无需手动安装配置。
|
||
|
||
### 方式二：npm 安装（推荐）
|
||
|
||
```bash
|
||
openclaw plugins install @sliverp/qqbot@1.3.7
|
||
```
|
||
|
||
### 方式三：源码安装
|
||
|
||
```bash
|
||
git clone https://github.com/sliverp/qqbot.git && cd qqbot
|
||
clawdbot plugins install .
|
||
```
|
||
|
||
> 💡 安装过程需要一些时间，尤其是小内存机器，请耐心等待
|
||
|
||
---
|
||
|
||
## ⚙️ 配置
|
||
|
||
### 1. 获取 QQ 机器人凭证
|
||
|
||
1. 访问 [QQ 开放平台](https://q.qq.com/)
|
||
2. 创建机器人应用
|
||
3. 获取 `AppID` 和 `AppSecret`（ClientSecret）
|
||
4. Token 格式：`AppID:AppSecret`
|
||
|
||
### 2. 添加配置
|
||
|
||
**交互式配置：**
|
||
|
||
```bash
|
||
clawdbot channels add
|
||
# 选择 qqbot，按提示输入 Token
|
||
```
|
||
|
||
**命令行配置：**
|
||
|
||
```bash
|
||
clawdbot channels add --channel qqbot --token "AppID:AppSecret"
|
||
```
|
||
|
||
### 3. 手动编辑配置（可选）
|
||
|
||
编辑 `~/.clawdbot/clawdbot.json`：
|
||
|
||
```json
|
||
{
|
||
"channels": {
|
||
"qqbot": {
|
||
"enabled": true,
|
||
"appId": "你的AppID",
|
||
"clientSecret": "你的AppSecret"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 配置项说明
|
||
|
||
| 配置项 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| `appId` | string | ✅ | QQ 机器人 AppID |
|
||
| `clientSecret` | string | ✅* | AppSecret，与 `clientSecretFile` 二选一 |
|
||
| `clientSecretFile` | string | ✅* | AppSecret 文件路径 |
|
||
| `enabled` | boolean | ❌ | 是否启用，默认 `true` |
|
||
| `name` | string | ❌ | 账户显示名称 |
|
||
| `systemPrompt` | string | ❌ | 自定义系统提示词 |
|
||
|
||
---
|
||
|
||
## 📨 支持的消息类型
|
||
|
||
| 事件类型 | 说明 | Intent |
|
||
|----------|------|--------|
|
||
| `C2C_MESSAGE_CREATE` | C2C 单聊消息 | `1 << 25` |
|
||
| `GROUP_AT_MESSAGE_CREATE` | 群聊 @机器人消息 | `1 << 25` |
|
||
| `AT_MESSAGE_CREATE` | 频道 @机器人消息 | `1 << 30` |
|
||
| `DIRECT_MESSAGE_CREATE` | 频道私信 | `1 << 12` |
|
||
|
||
---
|
||
|
||
## 🚀 使用
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
# 后台启动
|
||
clawdbot gateway restart
|
||
|
||
# 前台启动（查看日志）
|
||
clawdbot gateway --port 18789 --verbose
|
||
```
|
||
|
||
### CLI 配置向导
|
||
|
||
```bash
|
||
clawdbot onboard
|
||
# 选择 QQ Bot 进行交互式配置
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
- **群消息**：需要在群内 @机器人 才能触发回复
|
||
- **沙箱模式**：新创建的机器人默认在沙箱模式，需要添加测试用户
|
||
|
||
---
|
||
|
||
## 🔄 升级
|
||
|
||
### npm 热更新
|
||
|
||
```bash
|
||
npx -y @sliverp/qqbot@1.3.7 upgrade
|
||
```
|
||
|
||
> 热更新后无需重新配置 AppId 和 AppSecret
|
||
|
||
### 源码热更新
|
||
|
||
```bash
|
||
git clone https://github.com/sliverp/qqbot.git && cd qqbot
|
||
|
||
# 运行升级脚本
|
||
bash ./scripts/upgrade.sh
|
||
|
||
# 重新安装
|
||
clawdbot plugins install .
|
||
|
||
# 重新配置
|
||
clawdbot channels add --channel qqbot --token "AppID:AppSecret"
|
||
|
||
# 重启网关
|
||
clawdbot gateway restart
|
||
```
|
||
|
||
升级脚本会自动清理旧版本和配置。
|
||
|
||
---
|
||
|
||
|
||
|
||
---
|
||
|
||
## 📚 版本历史
|
||
|
||
<details>
|
||
<summary><b>v1.4.0（即将更新）</b></summary>
|
||
|
||
- 支持 Markdown 格式
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>v1.3.0 - 2026.02.03</b></summary>
|
||
|
||
- ✨ 支持图片收发等功能
|
||
- ✨ 支持定时任务到时后主动推送
|
||
- ✨ 支持使用 npm 等方式安装和升级
|
||
- 🐛 优化一些已知问题
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>v1.2.5 - 2026.02.02</b></summary>
|
||
|
||
- ✨ 解除 URL 发送限制
|
||
- ✨ 更新 Bot 正在输入中状态
|
||
- ✨ 提供主动推送能力
|
||
- 🐛 优化一些已知问题
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>v1.2.2 - 2026.01.31</b></summary>
|
||
|
||
- ✨ 支持发送文件
|
||
- ✨ 支持 openclaw、moltbot 命令行
|
||
- 🐛 修复 health 检查提示问题
|
||
- 🐛 修复文件发送后 clawdbot 无法读取的问题
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>v1.2.1</b></summary>
|
||
|
||
- 🐛 解决长时间使用会断联的问题
|
||
- 🐛 解决频繁重连的问题
|
||
- ✨ 增加大模型调用失败后的提示消息
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>v1.1.0</b></summary>
|
||
|
||
- 🐛 解决 URL 被拦截的问题
|
||
- 🐛 解决多轮消息发送失败的问题
|
||
- 🐛 修复部分图片无法接收的问题
|
||
- ✨ 增加支持 onboard 配置方式
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
## 🔗 相关链接
|
||
|
||
- [QQ 机器人官方文档](https://bot.q.qq.com/wiki/)
|
||
- [QQ 开放平台](https://q.qq.com/)
|
||
- [API v2 文档](https://bot.q.qq.com/wiki/develop/api-v2/)
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT
|