@sliverp/qqbot

QQ Bot Channel Plugin for Moltbot

QQ 开放平台 Bot API 的 Moltbot 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。

⭐ Star 趋势

📸 使用示例

✨ 功能特性

• 🔒 多场景支持 - C2C 私聊、群聊 @消息、频道消息、频道私信
• 🖼️ 富媒体消息 - 支持图片收发、文件发送
• ⏰ 定时推送 - 支持定时任务到时后主动推送
• 🔗 URL 无限制 - 私聊可直接发送 URL
• ⌨️ 输入状态 - Bot 正在输入中状态提示
• 🔄 热更新 - 支持 npm 方式安装和热更新
• 📝 Markdown - 支持 Markdown 格式（即将更新）

📦 安装

方式一：腾讯云 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

源码热更新

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 配置方式

🔗 相关链接

• QQ 机器人官方文档
• QQ 开放平台
• API v2 文档

📄 License

MIT