qqbot

核心用法

《QQ 官方机器人配置指南》是一份面向 OpenClaw 用户的实操教程，旨在帮助用户将 QQ 官方机器人（QQ Bot）接入 OpenClaw AI 平台。文档覆盖从创建机器人、获取凭证、配置 IP 白名单到启动守护进程的全链路步骤，并提供了针对 IP 不在白名单（错误 11298）、无法接收消息、依赖缺失、AI 回复超时等常见问题的排查方案。配套的 Python 脚本（qq_official_bot.py）通过 WebSocket 长连接与腾讯 API 交互，以文件队列机制与 OpenClaw 进行 IPC 通信，整体架构清晰且依赖精简（仅需 requests、aiohttp、websockets 三个知名 Python 库）。

显著优点

1. 操作门槛低：以分步骤教程形式呈现，每步均附带具体命令和截图指引，即使是新手也能按图索骥完成配置。
2. 问题覆盖全面：专门列出五大常见错误及解决方案，包括网络层（IP 白名单）、权限层（Intents）、依赖层（缺库）和业务层（消息事件、AI 超时），大幅降低试错成本。
3. 架构设计合理：主程序核心凭证采用占位符（"你的AppID"），消息处理不涉及系统命令执行或代码混淆，符合安全意识开发规范。
4. 依赖极轻量：仅依赖三个标准 Python 库，不引入额外框架，启动快速且便于维护。
5. 调试工具丰富：提供日志查看、WebSocket 连接监控、手动 AI 回复测试等调试手段，便于上线前验证。

潜在缺点或局限性

1. 网络环境依赖性强：必须拥有公网 IP，家庭宽带的动态 IP 需要频繁更新白名单，否则机器人会频繁断连。
2. 无官方组织背书：Skill 源自 ClawHub 个人开发者，缺少公开 GitHub 仓库或知名维护者历史，长期维护和安全性更新存在不确定性。
3. 示例凭证疑似泄露：config.example.json 中的 AppID 和 AppSecret 格式接近真实密钥，与文档宣称的"已脱敏"不符，存在被滥用的风险（即使文档建议重置）。
4. 发布脚本冗余：包内包含多个 Playwright 自动化脚本，用于开发者自行发布到 ClawHub，与核心 QQ Bot 功能无关，且引入了约 400MB 的 Playwright 依赖，可能误导用户安装不必要组件。
5. 许可证冲突：package.json 声明 ISC，但多处文档标注 MIT，法律声明不够严谨。

适合的目标群体

• 已部署 OpenClaw AI 并希望将其接入 QQ 生态的技术爱好者或个人开发者。
• 希望为私人群聊或客服场景搭建 AI 回复机器人的小型团队。
• 希望快速验证 QQ Bot 机器人可行性的学生或个人研究者。

使用风险

1. 凭证安全风险：用户必须严格保管从 QQ 开放平台获取的 AppSecret，且警惕示例配置中的疑似真实凭证，建议使用后立即重置。
2. 稳定性风险：依赖本地公网 IP 的部署方式在家庭宽带环境下极易因 IP 变更导致服务中断，若无备用方案（云服务器、内网穿透）则不适合生产环境。
3. 性能风险：Bot 单进程处理消息，通过文件队列与 AI 交互，高并发场景下可能出现排队延迟或文件系统 I/O 瓶颈。
4. 法律合规风险：QQ 官方对机器人的内容审核有严格限制，若 AI 生成违规内容，可能导致机器人被平台封禁，需配合腾讯内容安全策略使用。

核心用法

本Skill提供QQ官方机器人（QQ Bot）的完整配置指南，主要功能是将OpenClaw AI接入QQ平台，实现私聊和群聊中的AI对话能力。核心流程包括：在QQ开放平台注册机器人获取AppID/AppSecret → 配置公网IP白名单 → 修改OpenClaw配置文件 → 部署Python bot程序 → 启动守护进程。

技术架构采用WebSocket长连接接收消息事件，通过本地文件队列（qq_queue/目录）实现Bot与AI处理器的异步通信。支持GUILDS、GROUP_AND_C2C_EVENT、AT_MESSAGES三类Intents，覆盖频道、私聊、群@消息三种场景。

显著优点

1. 官方API稳定性：基于QQ官方机器人平台，相比第三方QQ协议库（如go-cqhttp、mirai），合规性更强，封号风险较低。

2. 文档详尽实用：覆盖从环境准备到故障排查的全流程，包含6个常见问题（IP白名单错误、消息接收失败、依赖缺失等）的具体现象-原因-解决方案，大幅降低踩坑成本。

3. 调试工具完善：提供日志过滤命令（grep -E "连接|心跳|收到"）、手动测试AI回复的脚本，便于快速定位问题。

4. 架构清晰解耦：Bot程序与AI处理器分离，通过文件队列通信，便于独立维护和扩展。

潜在缺点与局限性

1. 网络门槛较高：必须拥有公网IP，家庭宽带用户需处理动态IP变更（错误11298高频发生），长期使用建议云服务器。

2. 安全设计缺陷：安全报告显示存在config.example.json硬编码AppSecret的严重风险（RISK-001），用户可能直接复制误用导致凭证泄露。

3. 依赖管理问题：引入Playwright作为依赖，但仅用于发布脚本非运行时必需，却会在首次运行时自动下载100MB+浏览器二进制文件。

4. 个人维护风险：维护者为个人开发者"小皮"（T3来源等级），无组织背书，长期更新支持存在不确定性。

适合人群

• 具备Linux基础操作能力的技术用户
• 需要自建QQ Bot实现AI对话的个人开发者或小团队
• 已拥有云服务器或能解决公网IP问题的用户
• 不适合：无技术背景、期望一键部署的普通用户

常规风险

| 风险类型 | 等级 | 说明 |

|---------|------|------|

| 凭证泄露 | 🔴高 | 示例文件含硬编码AppSecret，误用将导致机器人被接管 |

| 动态IP失效 | 🟡中 | 家庭宽带IP变更后需手动更新白名单，服务中断 |

| 消息隐私 | 🟡中 | 用户消息经本地文件队列中转，日志可能记录敏感内容 |

| 依赖安全 | 🟢低 | Playwright浏览器下载来源可信，但体积大 |

合规建议：立即将config.example.json中的敏感字段替换为占位符；生产环境使用环境变量注入凭证替代配置文件；启用日志脱敏避免记录完整Token和用户消息。