（2224期）Qq – QQ 机器人官方开发全指南

QQ 机器人官方开发全指南 一站式 QQ 机器人开发指南，覆盖官方 Bot API 全链路（鉴权、WebSocket、Intents、Ark 卡片）与社区 OneBot 生态选型，含小程序及 OAuth2.0 接入 使用说明 核心定位 本技能为 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/GUILDMEMBERS/ATMESSAGES/GROUPANDC2C_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。 原始说明 QQ 机器人与开放平台开发指南。Use for: (1) 选择 QQ 机器人技术路线——官方 Bot API vs 社区 OneBot 生态, (2) 官方机器人从注册到上线全流程（鉴权/WebSocket网关/Intents/消息类型/Ark卡片）, (3) QQ 小程序与 OAuth2.0 接入。QQ bot...