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