Merge upstream/main into pr-to-upstream
Resolved conflicts: - package.json: Keep local version (@openclaw/qqbot 2026.1.31) - src/api.ts: Keep local comments - src/gateway.ts: Keep local features (qqimg tag support, local file handling, 60s timeout) - src/outbound.ts: Keep local implementation (rate limiting records) - README.md: Accept upstream version
This commit is contained in:
rianli
3
.gitignore
vendored
3
.gitignore
vendored
@@ -1,2 +1,3 @@
|
||||
node_modules
|
||||
dist
|
||||
dist
|
||||
distnode_modules
|
||||
|
||||
221
README.md
Normal file
221
README.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# QQ Bot Channel Plugin for Moltbot
|
||||
|
||||
QQ 开放平台Bot API 的 Moltbot 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- **多场景支持**：C2C 单聊、QQ 群 @消息、频道公开消息、频道私信
|
||||
- **自动重连**：WebSocket 断连后自动重连，支持 Session Resume
|
||||
- **消息去重**：自动管理 `msg_seq`，支持对同一消息多次回复
|
||||
- **系统提示词**：可配置自定义系统提示词注入到 AI 请求
|
||||
- **错误提示**：AI 无响应时自动提示用户检查配置
|
||||
|
||||
## 使用示例：
|
||||
<img width="1852" height="1082" alt="image" src="https://github.com/user-attachments/assets/a16d582b-708c-473e-b3a2-e0c4c503a0c8" />
|
||||
|
||||
## 版本更新
|
||||
<img width="1902" height="448" alt="Clipboard_Screenshot_1769739939" src="https://github.com/user-attachments/assets/d6f37458-900c-4de9-8fdc-f8e6bf5c7ee5" />
|
||||
|
||||
### 1.3.0（即将更新）
|
||||
- 支持回复图片等功能
|
||||
- 支持定时任务到时后主动推送
|
||||
|
||||
### 1.2.5-2026.02.02
|
||||
- 解除URL发送限制，现在可以直接在私聊发送URL
|
||||
<img width="1786" height="576" alt="Clipboard_Screenshot_1770092858" src="https://github.com/user-attachments/assets/c660949e-28a5-4e5f-abc2-77f0a2c67bad" />
|
||||
- 更新Bot正在输入中状态
|
||||
<img width="1440" height="412" alt="Clipboard_Screenshot_1770091969" src="https://github.com/user-attachments/assets/47835c4b-ccd2-4782-aaa6-b873cb58f7d7" />
|
||||
- 提供主动推送能力（目前AI还不知道怎么调用主动推送，相关完整Skill能力将在后续版本更新）
|
||||
- 优化一些已知问题
|
||||
- 优化未收到未收到大模型响应时的提示信息
|
||||
|
||||
|
||||
### 1.2.2
|
||||
- 支持发送文件
|
||||
- 支持openclaw、moltbot命令行
|
||||
- 修复[health]检查提示: [health] refresh failed: Cannot read properties of undefined (reading 'appId')的问题（不影响使用）
|
||||
- 修复文件发送后clawdbot无法读取的问题
|
||||
|
||||
### 1.2.1
|
||||
- 解决了长时间使用会断联的问题
|
||||
- 解决了频繁重连的问题
|
||||
- 增加了大模型调用失败后的提示消息
|
||||
|
||||
|
||||
### 1.1.0
|
||||
- 解决了一些url会被拦截的问题
|
||||
- 解决了多轮消息会发送失败的问题
|
||||
- 修复了部分图片无法接受的问题
|
||||
- 增加支持onboard的方式配置AppId 和 AppSecret
|
||||
|
||||
|
||||
## 安装
|
||||
|
||||
在插件目录下执行：
|
||||
|
||||
```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`，例如 `102146862:Xjv7JVhu7KXkxANbp3HVjxCRgvAPeuAQ`
|
||||
|
||||
### 2. 添加配置
|
||||
|
||||
#### 方式一：交互式配置
|
||||
|
||||
```bash
|
||||
clawdbot channels add
|
||||
# 选择 qqbot，按提示输入 Token
|
||||
```
|
||||
|
||||
#### 方式二：命令行配置
|
||||
|
||||
```bash
|
||||
clawdbot channels add --channel qqbot --token "AppID:AppSecret"
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
clawdbot channels add --channel qqbot --token "102146862:xxxxxxxx"
|
||||
```
|
||||
|
||||
### 3. 手动编辑配置（可选）
|
||||
|
||||
也可以直接编辑 `~/.clawdbot/clawdbot.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"qqbot": {
|
||||
"enabled": true,
|
||||
"appId": "你的AppID",
|
||||
"clientSecret": "你的AppSecret",
|
||||
"systemPrompt": "你是一个友好的助手"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 配置项说明
|
||||
|
||||
| 配置项 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| `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
|
||||
```
|
||||
|
||||
前台启动, 方便试试查看日志
|
||||
```bash
|
||||
clawdbot gateway --port 18789 --verbose
|
||||
```
|
||||
|
||||
### CLI 配置向导
|
||||
|
||||
```bash
|
||||
clawdbot onboard
|
||||
# 选择 QQ Bot 进行交互式配置
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **群消息**：需要在群内 @机器人 才能触发回复
|
||||
2. **沙箱模式**：新创建的机器人默认在沙箱模式，需要添加测试用户
|
||||
|
||||
## 升级
|
||||
|
||||
如果需要升级插件，先运行升级脚本清理旧版本：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
升级脚本会自动：
|
||||
- 删除 `~/.clawdbot/extensions/qqbot` 目录
|
||||
- 清理 `clawdbot.json` 中的 qqbot 相关配置
|
||||
|
||||
## 开发
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
npm install
|
||||
|
||||
# 编译
|
||||
npm run build
|
||||
|
||||
# 监听模式
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
qqbot/
|
||||
├── 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
|
||||
```
|
||||
|
||||
## 相关链接
|
||||
|
||||
- [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
|
||||
@@ -71,6 +71,26 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
|
||||
reload: { configPrefixes: ["channels.qqbot"] },
|
||||
// CLI onboarding wizard
|
||||
onboarding: qqbotOnboardingAdapter,
|
||||
// 消息目标解析
|
||||
messaging: {
|
||||
normalizeTarget: (target) => {
|
||||
// 支持格式: qqbot:c2c:xxx, qqbot:group:xxx, c2c:xxx, group:xxx, openid
|
||||
const normalized = target.replace(/^qqbot:/i, "");
|
||||
return { ok: true, to: normalized };
|
||||
},
|
||||
targetResolver: {
|
||||
looksLikeId: (id) => {
|
||||
// 先去掉 qqbot: 前缀
|
||||
const normalized = id.replace(/^qqbot:/i, "");
|
||||
// 支持 c2c:xxx, group:xxx, channel:xxx 格式
|
||||
if (normalized.startsWith("c2c:") || normalized.startsWith("group:") || normalized.startsWith("channel:")) return true;
|
||||
// 支持纯 openid（32位十六进制）
|
||||
if (/^[A-F0-9]{32}$/i.test(normalized)) return true;
|
||||
return false;
|
||||
},
|
||||
hint: "c2c:<openid> or group:<groupOpenid>",
|
||||
},
|
||||
},
|
||||
config: {
|
||||
listAccountIds: (cfg) => listQQBotAccountIds(cfg),
|
||||
resolveAccount: (cfg, accountId) => resolveQQBotAccount(cfg, accountId),
|
||||
|
||||
Reference in New Issue
Block a user