跳到主要内容

给Onebot11项目快速对接官方机器人！

· 阅读需 11 分钟
兔兔
兔兔

写这篇文章的起因，是我运营的Sparkbridge-群服mc机器人互通项目，作为一个onebot11的传统项目——需要小号挂机、容易掉线、动不动被风控，越来越多群友抱怨说bot登录不上，疯狂掉线，所以这俩天我都在想对策。

刚好看见有群友提到，现在其实 QQ 官方机器人（开放平台注册的那种）现在的能力还过得去，基本的信息获取都没问题，我就花了这几天时间，整理一下手头能想得到的方案，看中了之前经常使用的项目，Gensokyo，一个把"QQ 官方机器人 API"转换成"OneBot v11 协议"的转换器。

这个 Gensokyo 是什么，为什么现在要下载 fork 魔改的版本​

Gensokyo官方版本 上游本来就是把官方机器人 API 转成 OneBot 协议的转换器，但原版更新较慢，已经落后QQ官方的api更新大半年，缺少群服互通这类场景需要的能力，连获取全量信息都不支持。我也是根据我们bot互通需要的能力，基于上游重新 fork 魔改，得到了目前的产物：Gensokyo-ForSpark主要增加了：

  • 群全量消息接收（GROUP_MESSAGE_CREATE，不要求 @ 机器人）
  • 主动消息发送（无被动窗口也能直接发）
  • 官方昵称回填（sender.nickname/card 不再是空的）
  • 群聊管理全套：官方 2026-08 新增的群管理接口/事件（群成员加/退、入群申请与审批、禁言、机器人状态、入群自动审批策略等）
  • OneBot 兼容性修复：未支持的 action 也回合法 JSON（不再让对端等超时崩溃）、get_stranger_info 实现、入群审批兼容只传 flag 的插件、@ 的出入站转换等（做这个是发现有些api，请求的时候不支持就直接丢一个undefined回来，直接把bot崩溃了，就写了个保底）

其实关于这个get_stranger_info，他基本上没有什么实质功能，只是做了个虚拟保底。因为我发现有些新人识别插件会检测性别QQ等级啥的，所以就直接传个9999回来，这样也就避免无效值拉不了人。

需要说明：这个版本主要针对我们的SparkBridge 群服互通环境制作，不保证其他 OneBot v11 客户端能完美工作；但实现上遵循 OneBot v11 标准，理论上支持大多数 OB11 API。

方案优点​

  • 官方机器人接入：无需普通 QQ 小号挂机，不需要手机/电脑保持在线、不会被挤下线
  • 不掉线：官方 WebSocket 网关 + 自动重连，无登录态过期、无第三方协议风控，长期稳定
  • 全局信息：消息走官方云端 API，与客户端/设备解耦，重启即恢复
  • 不易封号：官方通道合法合规，不存在封杀第三方协议的风险

方案边界​

  • QQ号，群号全虚拟：官方里面所有的个人信息都是openid格式，gsk用md5算法转换为数字。无法获得真实QQ号群号。不过作为用户标记也勉强够用
  • 无真 @：官方不渲染 @ 标签，at 段会自动转成 @昵称 文本
  • 主动消息频控：Bot 维度 60 QPM（未认证 30 QPM），单关系 20 QPM，不适合高频刷屏
  • 官方接口能力有限：踢人、bot主动退群、改群名、拉取成员列表等官方 API 没有
  • 群管理操作，主动信息能力需群主亲自许可：入群审批、群禁言等需要机器人是群管理员，主动信息获取需要群主在手机 QQ 客户端给机器人配置权限
  • 部分资料不可得：QQ 等级、性别、年龄官方不提供
  • 链接域名校验：消息里的链接需过 QQ 校验，gsk 提供自动二维码/短链两种规避方式

第一步：申请一个 QQ 官方机器人​

配置注册bot流程也可以参考我之前配置 SparkbridgeBot 的视频：

BILIBILI[Sparkbridge3]对接官方！不掉线的基岩服务器Bot！

在开始配置前，你得先有一个官方机器人。流程很简单，几分钟搞定：

  1. 打开 QQ 开放平台，用 QQ 扫码登录
  2. 进入「应用管理」→ 创建应用，类型选机器人
  3. 填写应用信息（名称、简介、头像等），提交后不需要审核，秒过
  4. 注册完毕后，在「开发设置」里拿到三个关键凭据，保存好：
    • AppID（应用ID）
    • AppSecret（客户端密钥）（找不到就右上角切旧版平台 → 开发设置）
    • Token（应用令牌）
  5. 机器人创建后会自动出现在你的好友列表，把它拉进群：群主在qq群添加界面搜索机器人添加进群。没错，所以你最好是群主，这样流程最简单。
  6. 群主在手机 QQ 客户端给机器人配置权限：
    • 许可机器人获取信息范围为「所有消息」
    • 允许机器人在群内主动发言
    • （看不到选项就更新一下 QQ，9.2.90才有这个东西）
    • 需要入群审批、禁言等群管理功能的话，把机器人设为群管理员

权限不给齐，后面会各种"没反应"

收不到消息、主动消息报"无权限"、审批点不了。先配权限再往下走。

快速配置（不用手写 yaml）​

嫌弃自带的config太多乱七八糟的，看的头疼，搞了个可视化配置生成器，浏览器直接打开：

打开 Gensokyo 配置生成器

生成的配置不带官方注释

要自己改配置的话，建议先用官方配置生成一份对照着看，再手动加注释。

只需填：

必填说明
应用ID / 应用令牌 / 客户端密钥QQ 开放平台 → 开发设置
机器人QQ号点机器人资料卡查看
监听端口默认 15630
正向WS令牌你的 OneBot 客户端连接时用的密码

事件订阅全部勾选即可，然后下载生成的 config.yml 覆盖到 Gensokyo 目录，重启。

如果你不放心我的生成器，担心透露你的隐私——它是个纯前端静态页面，不发任何网络请求，可以 F12 自行审阅代码。

运行环境：需要下载编译好的 Gensokyo 可执行文件（GitHub 仓库），以及一个按上面流程申请的 QQ 官方机器人。

你的 OneBot 客户端怎么连​

你的客户端（AnyOneBot 框架/插件）用正向 WebSocket 连接 Gensokyo：

  • 地址：ws://Gensokyo所在机器IP:端口
  • 令牌：配置生成器里填的那个正向WS令牌

连上之后，框架收到的就是标准 OneBot v11 事件，原有的事件处理和 API 调用照常。

一个更重要的建议​

如果你的 OneBot 生态（NoneBot、Koishi 等）本身就有开箱即用的官方机器人适配器——比如 Koishi 的 qq-official、NoneBot 的 QQ 官方适配——优先用它们。官方适配器是社区为对应框架深度打磨的，类型定义、事件模型、文档都更完善。

这个魔改 Gensokyo 的价值，在于给"必须走 OneBot v11 协议"的项目（比如 SparkBridge 这类直接按 OneBot 协议对接的）一条接入官方机器人的路，省去小号挂机的烦恼。

常见问题​

Q: 连接不上，日志显示鉴权失败​

检查两边的令牌是否一致：Gensokyo 配置里的 ws_server_token 和你 OneBot 客户端连接时填的令牌必须完全相同。

Q: 日志报"主动消息失败, 无权限"​

官方机器人没有开通主动消息权限。让群主在手机 QQ 客户端给机器人开启"允许主动发言"。

Q: 群里收不到消息​

① Gensokyo 事件订阅里勾选群全量消息（GroupMessageEventHandler）；② 群主在手机 QQ 客户端许可机器人获取信息范围为「所有消息」。

Q: @ 显示不出来，只看到 @昵称 文字​

官方 API 不支持真 @ 标签，这是官方限制不是 bug，方案边界里也写了。

Q: 发出去的链接显示原文或被拦​

QQ 对消息里的链接有域名校验。在配置生成器⑤里选二维码模式（推荐）或短链模式（这个要自己配置白名单过审域名302跳转的）即可规避。

有问题欢迎留言交流。