核心定位
本技能为 QQ 开放平台开发提供完整技术指南，涵盖官方 Bot API与社区 OneBot 生态两条技术路线，支持频道、群聊、私聊、小程序及 OAuth2.0 授权体系的全栈开发。
核心用法
1. 技术路线选型
- 官方 Bot API：q.qq.com 注册，合规安全，适合商业产品；支持频道全功能，群/C2C 需审核开通
- 社区 OneBot：基于协议侧实现（NapCat、Lagrange 等），功能完整但存在封号风险，仅限个人自用
2. 官方机器人开发全流程
- 鉴权：Bearer Token 机制，AppID + AppSecret 获取 access_token（有效期 7200s）
- WebSocket 网关：Hello → Identify → Ready → 心跳维持，支持 session_id + seq 断线重连
- Intents 订阅：位掩码机制声明事件类型（GUILDS/GUILD_MEMBERS/AT_MESSAGES/GROUP_AND_C2C_EVENT 等）
- 消息体系：文本/Markdown/Ark 卡片/Embed/富媒体（type 0/2/3/4/7），群聊/C2C 强制被动回复
3. 高级能力
- Ark 模板消息：template_id 23/24 等卡片化交互
- OAuth2.0：标准授权码流程，获取用户昵称、头像、地域信息
- 小程序：QXML/QSS/JS 三件套，支持 QQ 钱包、厘米秀等特有能力
显著优点
- 官方合规：商业场景首选，无封号风险
- 架构清晰：WebSocket 事件驱动，Intents 灵活订阅
- 生态完善：官方 SDK + NoneBot2/Koishi 框架层
- 消息丰富：Ark 卡片实现类小程序的交互体验
潜在局限
- 功能受限：群/C2C 需人工审核，主动消息条数受限
- 频率瓶颈：全局 800 次/分钟，单频道 5 条/秒
- 门槛较高：Intents 位运算、WebSocket 状态机对新手不友好
- 审核依赖：商业能力开通周期长
适合人群
- 企业开发者：需要稳定、合规的 QQ 官方接入
- 频道运营者：内容自动化、会员管理、互动玩法
- 小程序开发者：QQ 生态扩展，社交裂变场景
- 技术决策者：评估官方 vs 社区路线的架构选型
常规风险
| 风险类型 | 说明 | 规避建议 |
|---------|------|---------|
| 凭证泄露 | AppSecret 暴露导致接口滥用 | 仅服务端存储，前端零硬编码 |
| 频率超限 | 触发 800 次/分钟全局限制 | 中心化 token 缓存 + 请求队列 |
| 会话中断 | WebSocket 异常断连丢事件 | 实现 Resume 重连机制 |
| 权限错误 | 未过审调用群/C2C 接口 | 沙箱充分测试，正式提审后上线 |
| 社区路线风控 | OneBot 实现被检测封号 | 个人自用场景，商业场景必选官方 |
信息来源评估
本文档由 ClawSkills Team 编写，API 端点、参数结构均引自 QQ 官方开放平台文档（bot.q.qq.com/wiki），代码示例为骨架级参考，未涉及协议逆向细节。来源可信度 T1。