13 · QQ 官方机器人协作教程

适用版本:ZL-综合插件 2.1.4(2026-10-09) 适用场景:UniQQ 同时登录 QQ 官方机器人和普通 QQ 机器人


一、先理解两个机器人的分工

2.1.4 的协作方式不是让两个机器人同时处理一遍消息,而是把“说话”和“执行”分开:

机器人负责内容
QQ 官方机器人菜单、AI、问答、提示、查询结果等所有对外回复;支持 Markdown 卡片、图片和官方艾特
普通 QQ 机器人在真实群后台执行禁言、解禁、踢人、撤回、全员禁言、管理员、群名片等框架动作

普通机器人执行成功后不会再重复发一套话术,最终结果仍由官机回复。这样既保留官方机器人的展示效果,又使用普通机器人的完整群管能力。

没有官机、官机离线、群未绑定或官机发送失败时,插件会自动回退普通机器人原有流程。因此只使用普通机器人的用户不受影响。


二、准备条件

开始前确认:

  1. UniQQ 已加载 ZL-综合插件 2.1.4。

  2. 框架里已经登录一个 QQ 官方机器人。

  3. 至少登录一个普通 QQ 机器人,且普通机器人已加入真实 QQ 群。

  4. 需要群管功能时,普通机器人必须是该群群主或管理员。

  5. 官方机器人与普通机器人需要对应同一业务群。

  6. 真实群已完成插件授权,分群配置也以真实群号为准。

只登录官方机器人可以回复部分消息,但禁言、踢人、撤回等动作没有执行端,不能完成完整群管。


三、开启官方协作

  1. 打开 UniQQ 插件管理,进入「ZL-综合插件 → 设置」。

  2. 在左侧打开「官方协作」。

  3. 查看「原生官方机器人」区域,确认官机显示在线。

  4. 开启协作模式并保存。

  5. 如果状态没有更新,点「刷新状态」。

「官方机器人 QQ 白名单」只填写已确认属于官机的真实 QQ。2.1.4 不再根据回复内容自动学习官机身份,避免有人复读官机消息后获得审核豁免;框架明确提供的官方虚拟机器人 ID 会自动保护。


四、绑定官方群和真实群

官方事件中的群号不是普通 QQ 群号,而是 19 位虚拟群 ID / openid。插件必须知道它对应哪个真实群,才能读取授权和分群配置,并把群管动作交给普通机器人。

推荐:三步快速绑定

  1. 插件主人一对一私信官机发送 绑定官机,取得 10 分钟有效验证码。

  2. 用同一个主人 QQ 私信普通机器人发送 确认官机 验证码。

  3. 回到已同时加入官机和普通机器人的同一个 QQ 群,先发送 绑定本群;再按提示明确 @官机发送 绑定本群 真实群号。

只有插件主人能完成第二步确认和群绑定。普通成员即使能看到官机,也不能把自己的 QQ 或群绑定到插件。

高级:控制台手动绑定

在「官方协作 → 群组绑定」中:

  1. 从“框架已识别的官方群”下拉框选择群;或手动输入官方虚拟群 ID。

  2. 输入对应的真实 QQ 群号。

  3. 点击「绑定」。

  4. 使用「测试发送」验证。

为什么下拉框没有某个群

框架只有收到该群的官方事件后才能识别它。请先在目标官方群中 @一次官方机器人或发送一条能触发机器人的消息,再回到控制台点击「刷新状态」。

绑定完成后,列表中的群名称、成员数量等信息以框架实际能提供的数据为准;官方接口未返回时会显示虚拟 ID,不影响绑定和消息处理。


五、成员身份映射

官方机器人收到的是 19 位成员虚拟 ID,普通机器人执行群管需要真实 QQ 号。2.1.4 会在官机事件与普通机器人真实群消息之间建立候选映射,但只有无歧义、已确认的映射才允许强操作。

自动映射

让目标成员在已绑定群中正常发言、艾特机器人或使用功能。框架同时收到两侧事件后,插件会按真实群、发送者和消息关联;多人同时发送相同内容时不会猜测身份。

手动映射

自动映射尚未建立时,在「官方协作 → 成员身份映射」填写:

  • 官方成员虚拟 ID;

  • 该成员真实 QQ 号;

  • 保存后重新执行禁言、踢人等操作。

出现“本群没有找到该成员”

按顺序检查:

  1. 官方群是否绑定到了正确的真实群。

  2. 普通机器人是否也在这个真实群。

  3. 目标成员是否在群内发过消息,让框架获得成员事件。

  4. 普通机器人是否能从真实群成员列表读取到该 QQ。

  5. 控制台成员映射是否指向正确 QQ。

不要直接把 19 位虚拟 ID 当作 QQ 号发送给禁言接口。


六、Markdown 菜单和卡片

内置菜单

2.1.2 起,存在可用官机时:

  • 菜单 默认发送新版 ZL Markdown 主菜单;

  • 所有内置子菜单同样使用分级标题、说明、引用和表情排版;

  • 没有官机时自动发送原普通消息菜单。

自定义菜单卡片

进入「菜单指令」,点击对应菜单右侧的「官机卡片」:

  1. 左侧填写官方 Markdown;

  2. 右侧查看实时预览;

  3. 保存后只影响官机回复;

  4. 清空卡片会回退该菜单默认文本或内置模板。

建议使用标准 Markdown:

# 一级标题
## 二级标题
**加粗文字**
> 引用说明
- 列表内容
![图片 #356px #120px](https://example.com/banner.png)

不要手写 <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 审核),官机自己的回复不会被普通机器人误撤。首次识别基于群名片/昵称与机器人昵称比对,日志可见:识别官机群成员别名(按昵称)。

⚠️ 注意:如果群成员故意把群名片改成和机器人一样,也会被豁免风控——不要把机器人昵称设得太通用(如"机器人""小助手")。


八、标准验收流程

绑定完成后依次测试:

  1. 发送 菜单:应由官机回复 Markdown 主菜单。

  2. 发送一个子菜单指令:应由官机回复对应 Markdown 子菜单。

  3. @官机 你好:应正常触发 AI 或配置的问答。

  4. 艾特另一个成员聊天:不应触发机器人 AI。

  5. 引用一条文字消息问“这是什么意思”:AI 应读到引用内容。

  6. 发图或引用图片询问:视觉模型应识别图片。

  7. 主人执行 禁言 @成员 1:同进程存在普通执行机器人时由它执行;只有官机时,仅在官方 OpenAPI 支持且虚拟成员映射已确认时执行,否则明确提示未执行。

  8. 发 小姐姐视频:官机应直接发出视频(失败时发文字链接)。

  9. 点一首歌:真音乐卡应由普通机器人发出(官机同时给文字回执)。

  10. 暂时关闭官机或协作开关后发 菜单:普通机器人应自动接管。


九、常见故障排查

官机什么都不回复

  • 检查官机是否在线、协作开关是否保存。

  • 检查官方群是否绑定真实群。

  • 检查真实群是否已授权、是否开启本群。

  • 官机被动回复凭据可能已过期:在群里重新 @官机后再试。

  • 查看控制台运行日志中的“官方消息投影”“关联真实群”和“消息路由”记录。

普通消息回复,艾特官机反而不回复

  • 确认艾特对象确实是当前官机,而不是其他机器人。

  • 更新到 2.1.4;旧版对官方艾特段解析与双通道路由不完整。

  • 检查日志中的原始消息段是否包含官方 at 段及机器人 openid。

同一条消息回复两次

  • 确认同一真实群只绑定一个官方群。

  • 检查是否有两个 UniQQ 实例同时加载插件。

  • 确认所有机器人都已升级到 2.1.4,避免旧实例未参与新防重。

  • 官机成功后普通机器人应静默;官机失败才允许回退。

禁言、踢人没有实际执行

  • 优先确认普通机器人在线并在真实群拥有管理员权限;只有官机时还需官方 OpenAPI 支持该动作。

  • 检查群绑定是否正确,执行日志中的“执行机器人”是否属于该真实群。

  • 检查目标成员虚拟 ID 是否已映射真实 QQ。

  • 机器人不能处理群主或权限高于自己的成员,这是 QQ 权限限制。

官机回复里出现 [图片]

  • 确认已升级 2.1.4。

  • 检查问答/欢迎语图片源是否仍然有效。

  • 官机卡片图片使用公网 HTTPS 链接;本地路径无法被 QQ 官方服务访问。

引用消息或图片没有被 AI 识别

  • 必须在引用后写清问题并 @官机。

  • 图片识别开关和视觉模型必须启用。

  • 闪照、已失效链接或无法下载的图片不能识别。

  • 查看日志是否成功解析引用消息 ID、引用文本和图片段。


十、推荐配置

  • 官机负责对外回复,普通机器人只负责动作执行。

  • 普通机器人不要退出真实群,也不要取消管理员权限。

  • 所有授权、功能开关和分群配置都在真实群维度维护。

  • 每个官方群只绑定一个真实群,避免路由歧义。

  • 先用默认 Markdown 菜单确认链路正常,再逐项自定义卡片。

  • 上传新版后必须重启 UniQQ;仍是旧行为时清理 Data\PluginRuntime 缓存再启动。

完成以上配置后,官机和普通机器人会作为一个整体工作:用户只看到官机回复,群管动作由普通机器人可靠落地。

共 27 篇 ZL-综合插件知识库 / QQ官方机器人协作教程 0 字 0 行 zhangxiaolin
创建 2026-10-07T19:18:15.687811096Z 更新 2026-10-13T08:14:40.315168894Z