openclaw/qqbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #40 from sliverp/feature/fix

Browse Source 
docs: 更新 README 格式和内容
This commit is contained in:
Bijin
2026-02-05 11:25:26 +08:00
committed by GitHub
parent 4fefa8f15b 98c7a598d8
commit d7a5ed6e0d
1 changed files with 151 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
README.md
View File

@@ -1,105 +1,96 @@
<div align="center">
# QQ Bot Channel Plugin for Moltbot # QQ Bot Channel Plugin for Moltbot
QQ 开放平台Bot API 的 Moltbot 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。 QQ 开放平台 Bot API 的 Moltbot 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。
## 使用示例： [![npm version](https://img.shields.io/badge/npm-v1.3.7-blue)](https://www.npmjs.com/package/@sliverp/qqbot)
<img width="600" height="2019" alt="Clipboard_Screenshot_1770195414" src="https://github.com/user-attachments/assets/6f1704ab-584b-497e-8937-96f84ce2958f" /> [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
[![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
[![Platform](https://img.shields.io/badge/platform-Moltbot-orange)](https://github.com/sliverp/moltbot)
[![Node.js](https://img.shields.io/badge/Node.js->=18-339933)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6)](https://www.typescriptlang.org/)
</div>
## 版本更新 ---
**使用`openclaw plugins list`来查看插件版本，建议使用最新版的版本**
<img width="902" height="248" alt="Clipboard_Screenshot_1769739939" src="https://github.com/user-attachments/assets/d6f37458-900c-4de9-8fdc-f8e6bf5c7ee5" />
### 1.4.0（即将更新） ## ⭐ Star 趋势
- 支持Markdonw格式
<!-- 在这里放置 Star 数量变化图 -->
### 1.3.0-2026.02.03
- 支持图片收发等功能
<img width="924" height="428" alt="Clipboard_Screenshot_1770112572" src="https://github.com/user-attachments/assets/80f38ae9-dc40-4545-ad17-e7e254064cf4" />
- 支持定时任务到时后主动推送 ---
<img width="930" height="288" alt="Clipboard_Screenshot_1770112539" src="https://github.com/user-attachments/assets/9674cda0-91e9-4860-8dcc-bc50007862a2" />
- 优化一些已知问题
- 支持使用npm等方式安装和升级（暂时不支持更低版本）
- 安装:`openclaw plugins install @sliverp/qqbot@1.3.7`
- 配置：`clawdbot channels add --channel qqbot --token "AppId:AppSecret"`
- 热更新：`npx -y @sliverp/qqbot@1.3.7 upgrade`。如果原来配置过AppId和AppSecret，热更新后无需再次配置。注意：npm和Openclaw会占用大量内存，小内存机器不建议使用，小内存机器建议参考下面源码热更新。
### 1.2.5-2026.02.02 ## 📸 使用示例
- 解除URL发送限制，现在可以直接在私聊发送URL
<img width="886" height="276" alt="Clipboard_Screenshot_1770092858" src="https://github.com/user-attachments/assets/c660949e-28a5-4e5f-abc2-77f0a2c67bad" />
- 更新Bot正在输入中状态
<img width="740" height="212" alt="Clipboard_Screenshot_1770091969" src="https://github.com/user-attachments/assets/47835c4b-ccd2-4782-aaa6-b873cb58f7d7" />
- 提供主动推送能力（目前AI还不知道怎么调用主动推送，相关完整Skill能力将在后续版本更新）
- 优化一些已知问题
- 优化未收到未收到大模型响应时的提示信息
<img width="600" alt="使用示例" src="https://github.com/user-attachments/assets/6f1704ab-584b-497e-8937-96f84ce2958f" />
### 1.2.2-2026.01.31 ---
- 支持发送文件
- 支持openclaw、moltbot命令行
- 修复[health]检查提示: [health] refresh failed: Cannot read properties of undefined (reading 'appId')的问题（不影响使用）
- 修复文件发送后clawdbot无法读取的问题
### 1.2.1 ## ✨ 功能特性
- 解决了长时间使用会断联的问题
- 解决了频繁重连的问题
- 增加了大模型调用失败后的提示消息
- 🔒 **多场景支持** - C2C 私聊、群聊 @消息、频道消息、频道私信
- 🖼️ **富媒体消息** - 支持图片收发、文件发送
- ⏰ **定时推送** - 支持定时任务到时后主动推送
- 🔗 **URL 无限制** - 私聊可直接发送 URL
- ⌨️ **输入状态** - Bot 正在输入中状态提示
- 🔄 **热更新** - 支持 npm 方式安装和热更新
- 📝 **Markdown** - 支持 Markdown 格式（即将更新）
### 1.1.0 ---
- 解决了一些url会被拦截的问题
- 解决了多轮消息会发送失败的问题
- 修复了部分图片无法接受的问题
- 增加支持onboard的方式配置AppId 和 AppSecret
## 📦 安装
## 安装 ### 方式一：腾讯云 Lighthouse 镜像（最简单）
现已发布npm，后续配置流程相同 [![Lighthouse](https://img.shields.io/badge/腾讯云-Lighthouse_镜像-00A4FF)](https://cloud.tencent.com/product/lighthouse)
`openclaw plugins install @sliverp/qqbot@1.3.7`
或者使用源码来安装，在插件目录下执行： 直接使用预装好的腾讯云 Lighthouse 镜像，开箱即用，无需手动安装配置。
### 方式二：npm 安装（推荐）
```bash
openclaw plugins install @sliverp/qqbot@1.3.7
```
### 方式三：源码安装
```bash ```bash
git clone https://github.com/sliverp/qqbot.git && cd qqbot git clone https://github.com/sliverp/qqbot.git && cd qqbot
clawdbot plugins install . # 这一步会有点久，需要安装一些依赖。稍微耐心等待一下，尤其是小内存机器 clawdbot plugins install .
``` ```
## 配置 > 💡 安装过程需要一些时间，尤其是小内存机器，请耐心等待
---
## ⚙️ 配置
### 1. 获取 QQ 机器人凭证 ### 1. 获取 QQ 机器人凭证
1. 访问 [QQ 开放平台](https://q.qq.com/) 1. 访问 [QQ 开放平台](https://q.qq.com/)
2. 创建机器人应用 2. 创建机器人应用
3. 获取 `AppID` 和 `AppSecret`（ClientSecret） 3. 获取 `AppID` 和 `AppSecret`（ClientSecret）
4. Token 格式为 `AppID:AppSecret`，例如 `102146862:Xjv7JVhu7KXkxANbp3HVjxCRgvAPeuAQ` 4. Token 格式：`AppID:AppSecret`
### 2. 添加配置 ### 2. 添加配置
#### 方式一：交互式配置 **交互式配置：**
```bash ```bash
clawdbot channels add clawdbot channels add
# 选择 qqbot，按提示输入 Token # 选择 qqbot，按提示输入 Token
``` ```
#### 方式二：命令行配置 **命令行配置：**
```bash ```bash
clawdbot channels add --channel qqbot --token "AppID:AppSecret" clawdbot channels add --channel qqbot --token "AppID:AppSecret"
``` ```
示例：
```bash
clawdbot channels add --channel qqbot --token "102146862:xxxxxxxx"
```
### 3. 手动编辑配置（可选） ### 3. 手动编辑配置（可选）
也可以直接编辑 `~/.clawdbot/clawdbot.json`： 编辑 `~/.clawdbot/clawdbot.json`：
```json ```json
{ {
@@ -107,27 +98,28 @@ clawdbot channels add --channel qqbot --token "102146862:xxxxxxxx"
"qqbot": { "qqbot": {
"enabled": true, "enabled": true,
"appId": "你的AppID", "appId": "你的AppID",
"clientSecret": "你的AppSecret", "clientSecret": "你的AppSecret"
"systemPrompt": "你是一个友好的助手"
} }
} }
} }
``` ```
---
## 📋 配置项说明
## 配置项说明
| 配置项 | 类型 | 必填 | 说明 | | 配置项 | 类型 | 必填 | 说明 |
|--------|------|------|------| |--------|------|------|------|
| `appId` | string | 是 | QQ 机器人 AppID | | `appId` | string | ✅ | QQ 机器人 AppID |
| `clientSecret` | string | 是* | AppSecret，与 `clientSecretFile` 二选一 | | `clientSecret` | string | ✅* | AppSecret，与 `clientSecretFile` 二选一 |
| `clientSecretFile` | string | 是* | AppSecret 文件路径 | | `clientSecretFile` | string | ✅* | AppSecret 文件路径 |
| `enabled` | boolean | 否 | 是否启用，默认 `true` | | `enabled` | boolean | ❌ | 是否启用，默认 `true` |
| `name` | string | 否 | 账户显示名称 | | `name` | string | ❌ | 账户显示名称 |
| `systemPrompt` | string | 否 | 自定义系统提示词 | | `systemPrompt` | string | ❌ | 自定义系统提示词 |
## 支持的消息类型 ---
## 📨 支持的消息类型
| 事件类型 | 说明 | Intent | | 事件类型 | 说明 | Intent |
|----------|------|--------| |----------|------|--------|
@@ -136,17 +128,17 @@ clawdbot channels add --channel qqbot --token "102146862:xxxxxxxx"
| `AT_MESSAGE_CREATE` | 频道 @机器人消息 | `1 << 30` | | `AT_MESSAGE_CREATE` | 频道 @机器人消息 | `1 << 30` |
| `DIRECT_MESSAGE_CREATE` | 频道私信 | `1 << 12` | | `DIRECT_MESSAGE_CREATE` | 频道私信 | `1 << 12` |
## 使用 ---
### 启动 ## 🚀 使用
### 启动服务
后台启动
```bash ```bash
# 后台启动
clawdbot gateway restart clawdbot gateway restart
```
前台启动, 方便试试查看日志 # 前台启动（查看日志）
```bash
clawdbot gateway --port 18789 --verbose clawdbot gateway --port 18789 --verbose
``` ```
@@ -157,23 +149,35 @@ clawdbot onboard
# 选择 QQ Bot 进行交互式配置 # 选择 QQ Bot 进行交互式配置
``` ```
## 注意事项 ---
1. **群消息**：需要在群内 @机器人 才能触发回复 ## ⚠️ 注意事项
2. **沙箱模式**：新创建的机器人默认在沙箱模式，需要添加测试用户
## 源码热更新 - **群消息**：需要在群内 @机器人 才能触发回复
- **沙箱模式**：新创建的机器人默认在沙箱模式，需要添加测试用户
如果需要升级插件，先运行升级脚本清理旧版本： ---
## 🔄 升级
### npm 热更新
```bash
npx -y @sliverp/qqbot@1.3.7 upgrade
```
> 热更新后无需重新配置 AppId 和 AppSecret
### 源码热更新
```bash ```bash
git clone https://github.com/sliverp/qqbot.git && cd qqbot git clone https://github.com/sliverp/qqbot.git && cd qqbot
# 运行升级脚本（清理旧版本和配置） # 运行升级脚本
bash ./scripts/upgrade.sh bash ./scripts/upgrade.sh
# 重新安装插件 # 重新安装
clawdbot plugins install . # 这一步会有点久，需要安装一些依赖。稍微耐心等待一下，尤其是小内存机器 clawdbot plugins install .
# 重新配置 # 重新配置
clawdbot channels add --channel qqbot --token "AppID:AppSecret" clawdbot channels add --channel qqbot --token "AppID:AppSecret"
@@ -182,49 +186,82 @@ clawdbot channels add --channel qqbot --token "AppID:AppSecret"
clawdbot gateway restart clawdbot gateway restart
``` ```
升级脚本会自动： 升级脚本会自动清理旧版本和配置。
- 删除 `~/.clawdbot/extensions/qqbot` 目录
- 清理 `clawdbot.json` 中的 qqbot 相关配置
## 开发 ---
```bash
# 安装依赖
npm install
# 编译
npm run build
# 监听模式 ---
npm run dev
```
## 文件结构 ## 📚 版本历史
``` <details>
qqbot/ <summary><b>v1.4.0（即将更新）</b></summary>
├── index.ts # 入口文件
├── src/
│ ├── api.ts # QQ Bot API 封装
│ ├── channel.ts # Channel Plugin 定义
│ ├── config.ts # 配置解析
│ ├── gateway.ts # WebSocket 网关
│ ├── onboarding.ts # CLI 配置向导
│ ├── outbound.ts # 出站消息处理
│ ├── runtime.ts # 运行时状态
│ └── types.ts # 类型定义
├── scripts/
│ └── upgrade.sh # 升级脚本
├── package.json
└── tsconfig.json
```
## 相关链接 - 支持 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://bot.q.qq.com/wiki/)
- [QQ 开放平台](https://q.qq.com/) - [QQ 开放平台](https://q.qq.com/)
- [API v2 文档](https://bot.q.qq.com/wiki/develop/api-v2/) - [API v2 文档](https://bot.q.qq.com/wiki/develop/api-v2/)
## License ---
## 📄 License
MIT MIT