QQ Bot Channel Plugin for Openclaw(Clawdbot/Moltbot)
QQ 开放平台 Bot API 的 Openclaw 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。
📸 使用示例
✨ 功能特性
- 🔒 多场景支持 - C2C 私聊、群聊 @消息、频道消息、频道私信
- 🖼️ 富媒体消息 - 支持图片收发、文件发送
- ⏰ 定时推送 - 支持定时任务到时后主动推送
- 🔗 URL 无限制 - 私聊可直接发送 URL
- ⌨️ 输入状态 - Bot 正在输入中状态提示
- 🔄 热更新 - 支持 npm 方式安装和热更新
- 📝 Markdown - 支持 Markdown 格式（即将更新）
⭐ Star 趋势
📦 安装
方式一：腾讯云 Lighthouse 镜像（最简单）
直接使用预装好的腾讯云 Lighthouse 镜像，开箱即用，无需手动安装配置。
方式二：npm 安装（推荐）
openclaw plugins install @sliverp/qqbot@1.3.7
方式三：源码安装
git clone https://github.com/sliverp/qqbot.git && cd qqbot
clawdbot plugins install .
💡 安装过程需要一些时间，尤其是小内存机器，请耐心等待
⚙️ 配置
1. 获取 QQ 机器人凭证
- 访问 QQ 开放平台
- 创建机器人应用
- 获取
AppID和AppSecret（ClientSecret） - Token 格式：
AppID:AppSecret
2. 添加配置
交互式配置：
clawdbot channels add
# 选择 qqbot，按提示输入 Token
命令行配置：
clawdbot channels add --channel qqbot --token "AppID:AppSecret"
3. 手动编辑配置（可选）
编辑 ~/.clawdbot/clawdbot.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 |
🚀 使用
启动服务
# 后台启动
clawdbot gateway restart
# 前台启动（查看日志）
clawdbot gateway --port 18789 --verbose
CLI 配置向导
clawdbot onboard
# 选择 QQ Bot 进行交互式配置
⚠️ 注意事项
- 群消息：需要在群内 @机器人 才能触发回复
- 沙箱模式：新创建的机器人默认在沙箱模式，需要添加测试用户
🔄 升级
npm 热更新
npx -y @sliverp/qqbot@1.3.7 upgrade
热更新后无需重新配置 AppId 和 AppSecret。该方式Openclaw和Node.js会占用大量内存，小内存机器优先建议使用源码方式热更新
源码热更新
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
升级脚本会自动清理旧版本和配置。
📚 版本历史
v1.4.0（即将更新）
- 支持 Markdown 格式
v1.3.0 - 2026.02.03
- ✨ 支持图片收发等功能
- ✨ 支持定时任务到时后主动推送
- ✨ 支持使用 npm 等方式安装和升级
- 🐛 优化一些已知问题
v1.2.5 - 2026.02.02
- ✨ 解除 URL 发送限制
- ✨ 更新 Bot 正在输入中状态
- ✨ 提供主动推送能力
- 🐛 优化一些已知问题
v1.2.2 - 2026.01.31
- ✨ 支持发送文件
- ✨ 支持 openclaw、moltbot 命令行
- 🐛 修复 health 检查提示问题
- 🐛 修复文件发送后 clawdbot 无法读取的问题
v1.2.1
- 🐛 解决长时间使用会断联的问题
- 🐛 解决频繁重连的问题
- ✨ 增加大模型调用失败后的提示消息
v1.1.0
- 🐛 解决 URL 被拦截的问题
- 🐛 解决多轮消息发送失败的问题
- 🐛 修复部分图片无法接收的问题
- ✨ 增加支持 onboard 配置方式
🔗 相关链接
📄 License
MIT