Skip to content

官方机器人协作教程 ​

适用场景:UniQQ 同时登录 QQ 官方机器人和普通 QQ 机器人。本篇讲解如何把「说话」交给官机、「执行」交给普通机器人,完成绑定、成员映射与验收。

🤝 两个机器人的分工 ​

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

机器人负责内容
QQ 官方机器人菜单、AI、问答、提示、查询结果等所有对外回复,支持 Markdown 卡片、图片和官方艾特
普通 QQ 机器人在真实群后台执行禁言、解禁、踢人、撤回、全员禁言、管理员、群名片等动作,并兜底发送定时 / 循环消息
  • 普通机器人执行成功后不重复发话术,最终结果仍由官机回复,既保留官方机器人的展示效果,又使用普通机器人的完整群管能力;
  • 没有官机、官机离线、群未绑定或官机发送失败时,自动回退普通机器人原有流程,只使用普通机器人的用户不受影响。

📋 准备条件 ​

  1. UniQQ 已加载 ZL-综合插件 2.1.4 及以上;
  2. 框架里已登录一个 QQ 官方机器人;
  3. 至少登录一个普通 QQ 机器人,且已加入真实 QQ 群;
  4. 需要群管功能时,普通机器人必须是该群群主或管理员;
  5. 官方机器人与普通机器人需要对应同一业务群;
  6. 真实群已完成插件授权,分群配置以真实群号为准。

WARNING

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

🔌 开启官方协作 ​

  1. 打开 UniQQ 插件管理,进入「ZL-综合插件 → 设置」;
  2. 在左侧打开「官方协作」;
  3. 查看「原生官方机器人」区域,确认官机显示在线;
  4. 开启协作模式并保存;
  5. 状态没有更新时,点「刷新状态」。

「官方机器人 QQ 白名单」只填写已确认属于官机的真实 QQ;框架明确提供的官方虚拟机器人 ID 会自动保护。

🔗 绑定官方群和真实群 ​

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

三步快速绑定(推荐) ​

  1. 插件主人一对一私信官机发送 绑定官机,取得 10 分钟有效验证码;
  2. 用同一个主人 QQ 私信普通机器人发送 确认官机 验证码;
  3. 回到已同时加入官机和普通机器人的同一个 QQ 群,先发送 绑定本群,再按提示明确 @官机 发送 绑定本群 真实群号。

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

控制台手动绑定 ​

在「官方协作 → 群组绑定」中:从「框架已识别的官方群」下拉框选择群(或手动输入官方虚拟群 ID)→ 输入对应的真实 QQ 群号 → 点击「绑定」→ 使用「测试发送」验证。

下拉框为什么没有某个群

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

👤 成员身份映射 ​

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

方式操作
自动映射让目标成员在已绑定群中正常发言、艾特机器人或使用功能,框架同时收到两侧事件后自动关联;多人同时发送相同内容时不会猜测身份
手动映射自动映射尚未建立时,在「官方协作 → 成员身份映射」填写官方成员虚拟 ID 与该成员真实 QQ 号,保存后重新执行禁言、踢人等操作

出现「本群没有找到该成员」时按顺序检查:官方群是否绑定到正确真实群 → 普通机器人是否也在该群 → 目标成员是否在群内发过消息 → 成员列表能否读到该 QQ → 映射是否指向正确 QQ。不要把 19 位虚拟 ID 直接当 QQ 号使用。

📝 Markdown 菜单和卡片 ​

内置菜单:存在可用官机时,菜单 默认发送 Markdown 主菜单,所有内置子菜单同样使用分级标题、说明、引用和表情排版;没有官机时自动发送原普通消息菜单。

自定义菜单卡片:「菜单指令」页点对应菜单右侧的「官机卡片」,左侧填写官方 Markdown、右侧实时预览,保存后只影响官机回复;清空卡片会回退该菜单默认文本或内置模板。

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

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(「定时任务」页编辑任务 → 底部「官机卡片」,左编辑右实时预览,支持 [群号] [群名] [日期] [时间] 等变量)。取舍规则:

  • 只填官机卡片:仅官机发卡片,普通号无文本可发自动跳过;
  • 两边都填:官机发卡片、普通号发纯文本,互不覆盖;
  • 都没填:拦截提示「发送内容与官机卡片至少填一项」。

✅ 标准验收流程 ​

绑定完成后依次测试:

  1. 发送 菜单:应由官机回复 Markdown 主菜单;
  2. 发送一个子菜单指令:应由官机回复对应 Markdown 子菜单;
  3. @官机 你好:应正常触发 AI 或配置的问答;
  4. 艾特另一个成员聊天:不应触发机器人 AI;
  5. 引用一条文字消息提问:AI 应读到引用内容;
  6. 发图或引用图片询问:视觉模型应识别图片;
  7. 主人执行 禁言 @成员 1:有普通执行机器人时由它执行;只有官机时,仅在官方接口支持且虚拟成员映射已确认时执行,否则明确提示未执行;
  8. 发 小姐姐视频:官机应直接发出视频(失败时发文字链接);
  9. 点一首歌:真音乐卡应由普通机器人发出,官机同时给文字回执;
  10. 暂时关闭官机或协作开关后发 菜单:普通机器人应自动接管。

🛠️ 常见故障排查 ​

故障排查
定时任务到点群里没消息官机群里属正常现象(拿不到被动凭据);确认「定时消息顺风车」开启,群里有人说句话就会补发;需严格准点则开「准点触发」并确保群内有普通机器人;日志可见「已挂入顺风车队列」或「顺风车超时丢弃」
官机什么都不回复检查官机在线与协作开关是否保存、官方群是否绑定真实群、真实群是否授权并开启;被动凭据过期时在群里重新 @官机再试;查看运行日志中的官方消息路由记录
普通消息回复,@官机反而不回复确认艾特对象确实是当前官机;升级到 2.1.4 及以上;检查日志中的原始消息是否包含官方 at 段
同一条消息回复两次确认同一真实群只绑定一个官方群;不要同时运行两个 UniQQ 实例;所有实例升级到 2.1.4 及以上;官机成功后普通机器人应静默
禁言、踢人没有实际执行优先确认普通机器人在线并在真实群有管理员权限;检查群绑定与成员映射是否正确;机器人不能处理群主或权限高于自己的成员,这是 QQ 权限限制
官机回复里出现「[图片]」确认已升级 2.1.4;检查问答 / 欢迎语图片源是否仍有效;卡片图片必须使用公网 HTTPS 链接,本地路径无法被官方服务访问
引用消息或图片没有被 AI 识别必须在引用后写清问题并 @官机;开启图片识别与视觉模型;闪照、失效链接或无法下载的图片不能识别

💡 推荐配置 ​

  • 官机负责对外回复,普通机器人只负责动作执行;
  • 普通机器人不要退出真实群,也不要取消管理员权限;
  • 所有授权、功能开关和分群配置都在真实群维度维护;
  • 每个官方群只绑定一个真实群,避免路由歧义;
  • 先用默认 Markdown 菜单确认链路正常,再逐项自定义卡片;
  • 上传新版后必须重启 UniQQ;仍是旧行为时清理 Data\PluginRuntime 缓存再启动。

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


📚 下一节:完整使用手册

薇薇官机平台 · ZL 系列插件