OpenQQ Bot
QQ bot integration for OpenClaw. Enables AI auto-reply for QQ private chats and group @mentions with session isolation and comprehensive logging.
Quick Start
CODEBLOCK0
Configuration
Edit ~/.openclaw/workspace/open-qq-config.json:
CODEBLOCK1
Get credentials from QQ Open Platform.
Usage
CODEBLOCK2
Features
- - Session Isolation: Each user/group has independent conversation history
- Private:
qq-private-{user_openid}
- Group:
qq-group-{group_openid}
- - Comprehensive Logging: China timezone, log rotation, sensitive data filtering
- Auto Reconnect: WebSocket auto-reconnect with heartbeat
- Message Retry: Auto-retry failed messages (up to 2 times)
- Graceful Shutdown: Clean shutdown on SIGTERM/SIGINT
Files
| File | Description |
|---|
| INLINECODE3 | Main program (WebSocket + OpenClaw integration) |
| INLINECODE4 |
Logging system (China timezone + rotation) |
|
scripts/health-check.sh | Health check script |
|
package.json | Dependencies (axios, ws) |
npm Commands
| Command | Description |
|---|
| INLINECODE7 | Start bot |
| INLINECODE8 |
Health check |
|
npm run logs | View logs |
|
npm run setup | Initialize config |
|
npm run status | Check status |
|
npm run clean | Clean node_modules |
Security
- - Do not commit
open-qq-config.json to version control - Set permissions: INLINECODE14
- Uses
spawn instead of exec to prevent command injection - Session IDs are whitelisted (alphanumeric + hyphen only)
Troubleshooting
| Issue | Solution |
|---|
| Config not found | Run INLINECODE17 |
| Missing credentials |
Edit config file with appId/token/appSecret |
| WebSocket failed | Check Token and network |
| No reply | Test with
openclaw agent --message "test" |
Changelog
See CHANGELOG.md
v0.0.3 (Latest)
- - 7 new npm commands
- FAQ section
- Message retry mechanism
- Graceful shutdown
License
MIT License
Links
OpenQQ Bot
为OpenClaw集成的QQ机器人。支持QQ私聊和群聊@提及的AI自动回复，具有会话隔离和全面的日志记录功能。
快速开始
bash
初始化配置
npm run setup
安装依赖
npm install
编辑配置
vim ~/.openclaw/workspace/open-qq-config.json
启动机器人
npm start
配置
编辑 ~/.openclaw/workspace/open-qq-config.json：
json
{
qq: {
appId: YOURAPPID,
token: YOUR_TOKEN,
appSecret: YOURAPPSECRET
}
}
从QQ开放平台获取凭证。
使用方法
bash
npm start # 启动机器人
npm run health # 健康检查
npm run logs # 查看今日日志
npm run status # 检查运行状态
功能特性
- 私聊：qq-private-{user_openid}
- 群聊：qq-group-{group_openid}
- - 全面日志记录：中国时区、日志轮转、敏感数据过滤
- 自动重连：WebSocket自动重连，带心跳检测
- 消息重试：失败消息自动重试（最多2次）
- 优雅关闭：收到SIGTERM/SIGINT信号时干净关闭
文件说明
| 文件 | 描述 |
|---|
| qq-bot.js | 主程序（WebSocket + OpenClaw集成） |
| logger.js |
日志系统（中国时区 + 轮转） |
| scripts/health-check.sh | 健康检查脚本 |
| package.json | 依赖项（axios, ws） |
npm命令
| 命令 | 描述 |
|---|
| npm start | 启动机器人 |
| npm run health |
健康检查 |
| npm run logs | 查看日志 |
| npm run setup | 初始化配置 |
| npm run status | 检查状态 |
| npm run clean | 清理node_modules |
安全
- - 不要将 open-qq-config.json 提交到版本控制
- 设置权限：chmod 600 ~/.openclaw/workspace/open-qq-config.json
- 使用 spawn 而非 exec 防止命令注入
- 会话ID经过白名单过滤（仅允许字母数字和连字符）
故障排除
| 问题 | 解决方案 |
|---|
| 找不到配置 | 运行 npm run setup |
| 缺少凭证 |
编辑配置文件，填入appId/token/appSecret |
| WebSocket连接失败 | 检查Token和网络 |
| 无回复 | 使用 openclaw agent --message test 测试 |
更新日志
详见 CHANGELOG.md
v0.0.3（最新版）
- - 新增7个npm命令
- 常见问题解答部分
- 消息重试机制
- 优雅关闭
许可证
MIT许可证
链接
