给Onebot11项目快速对接官方机器人!
· 阅读需 8 分钟
写这篇文章的起因,是我运营的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 提供自动二维码/短链两种规避方式
