QQ 官方机器人接入

← 入门与部署 · 所有分区

适用于 VexBot 0.6.30。此适配器使用 QQ 开放平台的 AppID / AppSecret、官方 REST 接口和 WebSocket Gateway，接收群聊与 C2C 单聊事件。应用需要具备对应的平台权限；此版本没有 HTTP Webhook 回调适配器。

配置步骤

1. 在 QQ 开放平台 创建机器人，取得开发设置中的 AppID 和 AppSecret，开通群聊 / 单聊场景，按平台要求配置测试范围或公网 IP 白名单。
2. 使用服主账号登录面板，进入「接入空间 → 机器人连接 → 接入设置」，选择「QQ 官方机器人」，填写 AppID 和 AppSecret，保存全部设置。
3. VexBot 主动获取访问凭证并连接官方网关。等待连接卡片显示「已连接」；失败原因会显示在卡片及日志中，连接诊断也会按当前接入方式给出提示。
4. 在需要关联的群内 @机器人 发送 接入信息。无需先添加服务器关联，机器人会返回该群与发送人的应用内身份。
5. 将返回的 qg:AppID:group_openid 整段填写到「服务器列表 → 关联 QQ 群 / 官机群身份」。将 qug:AppID:member_openid 整段填写到接入设置的官机管理员列表，保存后即可执行该服的预设命令。
6. 在关联群内 @机器人 发送 帮助、状态、在线 或 执行 在线检查。绑定仍是在对应游戏服输入 /qbind，然后在群内 @机器人 发送 绑定 验证码。

AppSecret 只在服主配置中保存，用于后端换取访问凭证；不会放入公开状态接口或部署配置导出。通用配置导入保留本机官机接入设置。AppID、密钥或接入方式变更会重建连接，并取消旧的群内远程指令任务，防止使用旧路由发送。

身份与兼容

官机 OpenID 不是普通 QQ 号，也不能据此推导 QQ 邮箱。VexBot 使用带应用与场景标记的身份：

前缀	用途
qg:AppID:	官方群身份，用于关联服务器及群权限范围
qug:AppID:	群内用户身份，用于群绑定、指令管理员、白名单申请及规则权限
qup:AppID:	单聊用户身份，在与机器人单聊发送 接入信息 获取

不同应用、群内与单聊身份分别保存，不自动关联到原有 QQ 号绑定。面板玩家绑定与白名单代申请接受上述用户身份；规则插件权限范围也接受官机身份。已有 OneBot 配置与数字 QQ 绑定保留，切回 OneBot 后继续按原身份使用。

支持范围

能力	官机行为
群服文字联动	接收平台下发的 @机器人群消息，关联后可同步到游戏
状态、在线查询、验证码绑定与解绑	支持，群内先 @机器人
预设指令、关键词回复与 JSON 群规则	支持，使用官机用户身份和已有权限检查
白名单申请	支持人工审核；要求本人 QQ 邮箱注册的限制无法自动通过 OpenID 关联，需使用网页流程或调整申请条件
单聊接入信息、登录确认指令	支持单聊事件；群绑定不自动变成单聊绑定。需要 QQ 私聊登录时须单独确认、建立对应单聊身份绑定和可用的消息发送权限，通常建议使用注册密码登录
游戏通知、定时公告与提醒	优先使用短期有效回复上下文；没有有效上下文时默认不尝试主动发送
主动发送	可在接入设置单独开启，仍受 QQ 平台权限、次数及内容审核约束
群名片、成员退群自动解绑	官方适配器不执行或模拟这些 OneBot 群管理能力
群内 QQ 邮箱注册	官机不能取得实际 QQ 号，使用社区注册网页验证邮箱
指定指令图片回复	支持本地 PNG 上传与富媒体引用发送，需平台图片权限、回复上下文或主动发送权限；见 图片回复设置
频道、其他富媒体、Webhook	此版本不提供；入站附件在文字联动中仅作提示

官机模式不等于收到群内所有聊天，也不保证任意时刻都能推送通知。接入成功与权限、消息投递成功分别核对；发送失败会记录错误，不自动重放业务消息。

验证范围与官方资料

协议测试使用隔离的官方接口模拟服务，验证访问凭证缓存与刷新、Identify / 心跳 / Resume、群与单聊身份、消息引用、绑定、管理员指令及配置权限。没有使用真实 AppID / AppSecret 完成腾讯平台实测；上线时需使用自己的应用按上述步骤验收。

• 获取访问凭证
• API 调用与唯一身份机制
• 事件订阅、WebSocket 与群聊 / 单聊事件