跳转至

QQ Bot 通道调研（官方开放平台 + 非官方个人号）

历史记录 / Historical record：本文保留当时的计划、研究或验收证据，不代表 0.11 当前能力全集。现行说明见 文档入口；英文入口见 English overview。

最后更新：2026-10-09 ｜ 调研基线：QQ 开放平台官方文档（bot-docs，q.qq.com）与社区现状 结论先行：官方 bot 免费合法但能力残缺（主动消息已停、文件类富媒体不开放、被动回复窗口短）；非官方 NTQQ 系（NapCat/Milky 系）功能完整但持续被官方打击、封号风险高。QQ 对 OneTHU 只适合做「弱通知 + 群助手」定位。

1. 官方 QQ 开放平台机器人

1.1 接入路径与注册

  • 平台：QQ 开放平台 q.qq.com，手机 QQ 扫码注册/登录，创建机器人得 AppID + AppSecret（Secret 离开页面即不可见，需重置）。个人开发者可注册（需实名），沙箱环境与正式环境分离，正式上架需审核（待验证当前个人开发者审核通过率与类目限制）。
  • openclaw 生态有腾讯 QQ 开放平台团队出品的官方插件 @tencent-connect/openclaw-qqbot（WebSocket 网关接入）。

1.2 认证与事件

  • AppID + AppSecret → access_token（client_credentials 类语义，有效期与刷新以官方 SDK 实现为准）。
  • 事件接入：WebSocket / WebSocket 反向为主（openclaw 插件即 WS 网关 + 断线重连 + resume 序列），webhook 可选；无需公网入口，NAS 友好。

1.3 消息规则（重点，直接决定产品形态）

来源：官方 bot-docs 发送消息（raw：send.md）：

主动推送能力于 2025 年 4 月 21 日起不再提供，接口调用会收到错误信息（官方公告）。

场景 被动回复（msg_id 回复） 主动消息
QQ 单聊（C2C） 窗口 60 分钟，每条消息最多回复 5 次 原 4 条/月/人，2025-04-21 起停用
QQ 群聊 窗口 5 分钟，每条消息最多 5 次 原 4 条/月/群，2025-04-21 起停用
文字子频道 窗口 5 分钟；子频道 ≤5 条/秒 每子频道 20 条/天（限 2 个子频道/频道/天）
频道私信 窗口 5 分钟 2 条/人/天，累计 200 条/天
  • 群内触发默认需 @机器人；用户可在客户端关闭接收 bot 主动消息（存量能力）。
  • 消息含 URL 须在 q.qq.com 后台「消息 URL 配置」白名单，否则发送失败。
  • 回复序号 msg_seq 与 msg_id 联合防重。

1.4 文件收发（硬需求核验）

  • 富媒体（rich-media.md）：POST /v2/users/{openid}/files（单聊）/ POST /v2/groups/{group_openid}/files（群聊），file_type：1 图片(png/jpg)、2 视频(mp4)、3 语音(silk)、4 文件（暂不开放）；媒体源仅支持 URL（url 字段，QQ 服务器主动拉取；file_data 本地上传「暂未支持」），file_info 有 ttl 有效期，单聊/群聊素材不互通。
  • 即官方通道发不了通用文件（图片/视频/语音之外），且发送素材需要公网可拉取的 URL（OneTHU 需要云盘直链或对象存储中转）。接收侧：入站图片/视频/语音事件带 file_info.url 可下载（有效期有限，待验证是否覆盖文件类消息——文档未列出「文件」入站类型，按不支持对待）。
  • openclaw qqbot 插件文档声称 C2C/群支持 files 且 ≥5MiB 走「QQ 分块上传端点」——与 bot-docs master「file_type 4 暂不开放」冲突，疑为插件使用了未公开/灰度端点，待验证。
  • 结论：官方 QQ 通道不满足「IM 传文件进云盘」硬需求，只满足图片/视频类。

1.5 SDK 与合规

  • 官方：Python qq-botpy、Node qq-bot-sdk；社区 Rust 无成熟官方 API 实现（需自写，API 面小）。openclaw 插件（TS）可作参考实现。
  • 合规：官方认可、免费；内容审核（平台侧）；机器人名称/能力审核。无账号封禁概念（应用维度治理）。

2. 非官方 QQ 个人号方案（如实评估，高风险）

来源：海豹手册 QQ 平台页（长期跟踪 QQ bot 生态的社区文档）+ 项目文档。核心事实：

「QQ 官方一直在对第三方实现进行技术与非技术层面的多重打击。当 QQ 账号用作机器人并被检测到时，会被警告、封禁、临时甚至永久冻结。这些方案实质上以 QQ 官方角度等同于『外挂软件』。」

方案 原理 2026-10 现状 风险
NapCat（NapNeko/NapCat） 无头官方 NTQQ 客户端（跑真客户端内核），对外暴露 OneBot 11 仍在维护、活跃；有风控掉线 issue（如 #1728 登录被风控检测频繁掉线）；QQ 客户端不能随意升级（升级即可能失效） 高：占用 PC 登录位、检测随版本演进、有冻结案例
Lagrange.OneBot NTQQ 协议纯模拟（C#） 已死：LagrangeV2 不再支持 OneBot 11，V1 实现停止维护（官方文档 FAQ） 高（且主线已转向 Milky）
Lagrange.Milky / Yogurt LagrangeV2 / acidify-core 实现 Milky 协议（OneBot 11 后继） 活跃维护；需自行申请 Signer Token（签名服务），社区签名服务随时可能被打击 高
LLBot（原 LLOneBot） LiteLoaderQQNT 插件形态 v8.0.9+ 需向开发组申请 AUTH TOKEN（中心化门禁） 高
Go-Cqhttp Android 协议 基本不可用，社区已弃用（海豹手册明确建议迁移） 不可用

共性风险：协议端与 QQ 版本强耦合；占用 PC 端登录位；封禁/冻结不可申诉；Docker headless 部署可行（NapCat 官方支持）但风控检测对 headless/异地登录特征更敏感。不建议 OneTHU 默认集成；如做，仅作为用户自担风险的可选组件（自带 QQ 小号）。

3. 对 OneTHU 的结论

  1. 官方通道：适合「通知弱通道 + 群内 @ 助手」定位，不能承担文件传输主通道；被动 5 次回复窗口对 agent 长任务不友好（5 分钟窗口内 agent 没跑完就没法回了——除非用 markdown/卡片的消息更新类接口原地编辑，待验证群聊卡片编辑能力）。
  2. 非官方通道：文件收发能力完整（OneBot 11/Milky 均支持群文件），但封号风险与维护成本高，不进默认能力。
  3. 优先级排在微信 iLink / 飞书之后（企微已在无后端主案下出局）；若目标用户（清华学生）QQ 使用率确有数据支撑，再以官方通道小规模试水。

参考