13 · QQ 官方机器人协作教程
适用版本:ZL-综合插件 2.1.4(2026-10-09) 适用场景:UniQQ 同时登录 QQ 官方机器人和普通 QQ 机器人
一、先理解两个机器人的分工
2.1.4 的协作方式不是让两个机器人同时处理一遍消息,而是把“说话”和“执行”分开:
| 机器人 | 负责内容 |
|---|---|
| QQ 官方机器人 | 菜单、AI、问答、提示、查询结果等所有对外回复;支持 Markdown 卡片、图片和官方艾特 |
| 普通 QQ 机器人 | 在真实群后台执行禁言、解禁、踢人、撤回、全员禁言、管理员、群名片等框架动作 |
普通机器人执行成功后不会再重复发一套话术,最终结果仍由官机回复。这样既保留官方机器人的展示效果,又使用普通机器人的完整群管能力。
没有官机、官机离线、群未绑定或官机发送失败时,插件会自动回退普通机器人原有流程。因此只使用普通机器人的用户不受影响。
二、准备条件
开始前确认:
UniQQ 已加载 ZL-综合插件 2.1.4。
框架里已经登录一个 QQ 官方机器人。
至少登录一个普通 QQ 机器人,且普通机器人已加入真实 QQ 群。
需要群管功能时,普通机器人必须是该群群主或管理员。
官方机器人与普通机器人需要对应同一业务群。
真实群已完成插件授权,分群配置也以真实群号为准。
只登录官方机器人可以回复部分消息,但禁言、踢人、撤回等动作没有执行端,不能完成完整群管。
三、开启官方协作
打开 UniQQ 插件管理,进入「ZL-综合插件 → 设置」。
在左侧打开「官方协作」。
查看「原生官方机器人」区域,确认官机显示在线。
开启协作模式并保存。
如果状态没有更新,点「刷新状态」。
「官方机器人 QQ 白名单」只填写已确认属于官机的真实 QQ。2.1.4 不再根据回复内容自动学习官机身份,避免有人复读官机消息后获得审核豁免;框架明确提供的官方虚拟机器人 ID 会自动保护。
四、绑定官方群和真实群
官方事件中的群号不是普通 QQ 群号,而是 19 位虚拟群 ID / openid。插件必须知道它对应哪个真实群,才能读取授权和分群配置,并把群管动作交给普通机器人。
推荐:三步快速绑定
插件主人一对一私信官机发送
绑定官机,取得 10 分钟有效验证码。用同一个主人 QQ 私信普通机器人发送
确认官机 验证码。回到已同时加入官机和普通机器人的同一个 QQ 群,先发送
绑定本群;再按提示明确 @官机发送绑定本群 真实群号。
只有插件主人能完成第二步确认和群绑定。普通成员即使能看到官机,也不能把自己的 QQ 或群绑定到插件。
高级:控制台手动绑定
在「官方协作 → 群组绑定」中:
从“框架已识别的官方群”下拉框选择群;或手动输入官方虚拟群 ID。
输入对应的真实 QQ 群号。
点击「绑定」。
使用「测试发送」验证。
为什么下拉框没有某个群
框架只有收到该群的官方事件后才能识别它。请先在目标官方群中 @一次官方机器人或发送一条能触发机器人的消息,再回到控制台点击「刷新状态」。
绑定完成后,列表中的群名称、成员数量等信息以框架实际能提供的数据为准;官方接口未返回时会显示虚拟 ID,不影响绑定和消息处理。
五、成员身份映射
官方机器人收到的是 19 位成员虚拟 ID,普通机器人执行群管需要真实 QQ 号。2.1.4 会在官机事件与普通机器人真实群消息之间建立候选映射,但只有无歧义、已确认的映射才允许强操作。
自动映射
让目标成员在已绑定群中正常发言、艾特机器人或使用功能。框架同时收到两侧事件后,插件会按真实群、发送者和消息关联;多人同时发送相同内容时不会猜测身份。
手动映射
自动映射尚未建立时,在「官方协作 → 成员身份映射」填写:
官方成员虚拟 ID;
该成员真实 QQ 号;
保存后重新执行禁言、踢人等操作。
出现“本群没有找到该成员”
按顺序检查:
官方群是否绑定到了正确的真实群。
普通机器人是否也在这个真实群。
目标成员是否在群内发过消息,让框架获得成员事件。
普通机器人是否能从真实群成员列表读取到该 QQ。
控制台成员映射是否指向正确 QQ。
不要直接把 19 位虚拟 ID 当作 QQ 号发送给禁言接口。
六、Markdown 菜单和卡片
内置菜单
2.1.2 起,存在可用官机时:
菜单默认发送新版 ZL Markdown 主菜单;所有内置子菜单同样使用分级标题、说明、引用和表情排版;
没有官机时自动发送原普通消息菜单。
自定义菜单卡片
进入「菜单指令」,点击对应菜单右侧的「官机卡片」:
左侧填写官方 Markdown;
右侧查看实时预览;
保存后只影响官机回复;
清空卡片会回退该菜单默认文本或内置模板。
建议使用标准 Markdown:
不要手写 <qqbot-cmd-input> 等扩展标签。部分 QQ 客户端会把不支持的标签原样显示;内置菜单已经改用平台可识别的标准 Markdown 形式。
问答、欢迎语和其他场景
问答管理、群聊提示等支持单独设置「官机卡片」。如果同时配置普通文本和官机卡片:
官机群使用官机卡片;
无官机群使用普通文本;
图片应使用可公网访问的 HTTPS 地址。
七、艾特、引用与图片识别
艾特官方机器人
在官方群中 @官机并提问,插件会去掉对机器人的艾特标记,再把正文交给菜单、问答或 AI。仅艾特其他群成员时不会触发 AI。
艾特群成员
警告、禁言结果等消息需要艾特成员时,插件会优先用官方成员 openid 生成真实官方艾特;映射不足或消息结构不适合官机时会安全回退普通机器人。
引用消息
引用一条文字消息后提问:
AI 会把引用文字与本次问题一起分析。
引用图片或当前图片
可以直接发图并 @机器人,也可以引用带图消息再提问。插件会把当前消息和引用消息中的图片交给视觉模型。需要在 AI 中心配置支持图片的视觉模型。
视频(2.1.4 起)
官机通过官方富媒体接口直接发送视频(小姐姐视频 / 随机小姐姐 等指令):
视频源必须是公网可访问的 mp4 直链,官方平台软限制 30MB;
视频与文字合并为一条富媒体消息发出;
视频上传失败时自动降级为"视频链接"文字消息,文字部分照常发送。
音乐卡片(2.1.4 起)
官方平台限制:QQ 官方机器人在群聊不能发送 ark/json 卡片(仅 3 种申请制固定模板),音乐卡无法由官机直发。2.1.4 的处理方式:
联动群普通执行机器人在线时:普通号把真音乐卡(带播放按钮)发进真实群,官机只发一句简短回执(不重复暴露音频链接);
普通号不在线或未加入真实群时:官机发纯文字说明自动降级。
官机别名保护(2.1.4 起)
官机在真实群里表现为一个普通成员号(别名号)。插件会自动识别这个别名号并豁免全部风控处罚(黑名单、违禁词、刷屏、按类型主动撤回、AI 审核),官机自己的回复不会被普通机器人误撤。首次识别基于群名片/昵称与机器人昵称比对,日志可见:识别官机群成员别名(按昵称)。
⚠️ 注意:如果群成员故意把群名片改成和机器人一样,也会被豁免风控——不要把机器人昵称设得太通用(如"机器人""小助手")。
八、标准验收流程
绑定完成后依次测试:
发送
菜单:应由官机回复 Markdown 主菜单。发送一个子菜单指令:应由官机回复对应 Markdown 子菜单。
@官机 你好:应正常触发 AI 或配置的问答。艾特另一个成员聊天:不应触发机器人 AI。
引用一条文字消息问“这是什么意思”:AI 应读到引用内容。
发图或引用图片询问:视觉模型应识别图片。
主人执行
禁言 @成员 1:同进程存在普通执行机器人时由它执行;只有官机时,仅在官方 OpenAPI 支持且虚拟成员映射已确认时执行,否则明确提示未执行。发
小姐姐视频:官机应直接发出视频(失败时发文字链接)。点一首歌:真音乐卡应由普通机器人发出(官机同时给文字回执)。
暂时关闭官机或协作开关后发
菜单:普通机器人应自动接管。
九、常见故障排查
官机什么都不回复
检查官机是否在线、协作开关是否保存。
检查官方群是否绑定真实群。
检查真实群是否已授权、是否开启本群。
官机被动回复凭据可能已过期:在群里重新 @官机后再试。
查看控制台运行日志中的“官方消息投影”“关联真实群”和“消息路由”记录。
普通消息回复,艾特官机反而不回复
确认艾特对象确实是当前官机,而不是其他机器人。
更新到 2.1.4;旧版对官方艾特段解析与双通道路由不完整。
检查日志中的原始消息段是否包含官方
at段及机器人 openid。
同一条消息回复两次
确认同一真实群只绑定一个官方群。
检查是否有两个 UniQQ 实例同时加载插件。
确认所有机器人都已升级到 2.1.4,避免旧实例未参与新防重。
官机成功后普通机器人应静默;官机失败才允许回退。
禁言、踢人没有实际执行
优先确认普通机器人在线并在真实群拥有管理员权限;只有官机时还需官方 OpenAPI 支持该动作。
检查群绑定是否正确,执行日志中的“执行机器人”是否属于该真实群。
检查目标成员虚拟 ID 是否已映射真实 QQ。
机器人不能处理群主或权限高于自己的成员,这是 QQ 权限限制。
官机回复里出现 [图片]
确认已升级 2.1.4。
检查问答/欢迎语图片源是否仍然有效。
官机卡片图片使用公网 HTTPS 链接;本地路径无法被 QQ 官方服务访问。
引用消息或图片没有被 AI 识别
必须在引用后写清问题并 @官机。
图片识别开关和视觉模型必须启用。
闪照、已失效链接或无法下载的图片不能识别。
查看日志是否成功解析引用消息 ID、引用文本和图片段。
十、推荐配置
官机负责对外回复,普通机器人只负责动作执行。
普通机器人不要退出真实群,也不要取消管理员权限。
所有授权、功能开关和分群配置都在真实群维度维护。
每个官方群只绑定一个真实群,避免路由歧义。
先用默认 Markdown 菜单确认链路正常,再逐项自定义卡片。
上传新版后必须重启 UniQQ;仍是旧行为时清理
Data\PluginRuntime缓存再启动。
完成以上配置后,官机和普通机器人会作为一个整体工作:用户只看到官机回复,群管动作由普通机器人可靠落地。