开始前,先记住三句话
这三条能避免 90% 的「拉了群却没反应」「群号填了不生效」。
群号只需配对一次
腾讯只给机器人一串 32 位内部标识,不提供 QQ 群号。第一次用「指定群」功能时,在「配群号」里把群和群号对一次,之后所有地方直接填群号。
顺序不能反
先启动客户端,再把机器人拉进群,最后在群里 @ 它一次。机器人靠群消息事件发现新群,顺序反了就会「拉取不到群」。
不指定群也能用
不填群号时,聊天、命令、监控、定时会对所有已发现的群生效。只有需要「只对某个群」生效时,才要配群号。
全流程一图看懂
前四步跑通基础聊天,第五步开始做「按群」配置。第一次部署建议按顺序走完。
最容易被跳过的一步:拉群之前,客户端必须已经启动并显示在线;拉群之后,必须有人在群里 @ 机器人一次。两条都满足,客户端才能发现这个群。
安装并登录客户端
装好、登录、确认会员状态。安装包已自带运行环境,不需要另外装 .NET。
装好客户端,能进主界面
Windows 10 / 11 · 64 位 · 需要管理员权限
- 双击 PaofuBot_v6.1.3.9_Setup.exe,按提示点「下一步」。安装需要管理员权限,默认装到
C:\Program Files\泡芙Bot,可以勾选创建桌面图标。 - 如果 Windows 弹出「已保护你的电脑」,先确认安装包来自你信任的渠道,再点「更多信息」→「仍要运行」。
- 打开客户端,注册或登录泡芙账号。注册需要收邮箱验证码,按页面提示填写即可。
- 如果提示「会员已过期」,点「充值 / 续费」完成后再重新登录。
- 看到主界面,就说明安装和登录都完成了。客户端之后会自动检查更新,收到提示按提示升级即可,不用反复重装。
安装路径、桌面图标都不影响后续配置。如果电脑装了多个用户账号,请固定用同一个 Windows 账号运行客户端,配置会保存在该用户的 %APPDATA%\PaofuBot 下。
创建 QQ 官方机器人,拿到凭据
机器人要在 QQ 开放平台创建。你需要两样东西:AppID 和 AppSecret。
在 q.qq.com 创建机器人
开发设置 → AppID / AppSecret → 按需提交上线
- 浏览器打开 q.qq.com(QQ 开放平台),用 QQ 登录。
- 创建一个机器人,按平台要求填写资料。个人还是企业主体,按你的实际情况选择。
- 进入「开发设置」,复制 AppID 和 AppSecret。AppSecret 通常只完整显示一次,先存到安全的地方。
- 开发阶段的机器人只能在自己有管理权限的测试群里使用;要给客户群用,按平台流程提交上线。
一个 AppID 就是一个机器人身份。换 AppID 等于换了一个机器人:之前的群号配对、主人设置全部作废,需要重新配。确定好用哪个机器人再开始。
官方通道默认只能收到「群内 @机器人」和「私聊」消息。未 @ 的普通群消息需要平台开通「全部群消息」权限;群管、监控等能力也受平台接口限制,具体以平台返回为准。
只填两个关键设置
先让「官方通道」和「AI 回复」跑通,其他开关暂时不用动。
官方通道 + AI 回复
主界面右下角「设置」;AI 设置在主界面的「AI回复设置」
- 点主界面右下角的 「设置」。
- 找到 「QQ 官方机器人通道(合规接入)」,勾选开关。
- 填入刚复制的 AppID 和 AppSecret。
- 点 「保存设置」。AppSecret 只保存在本机,不会上云。
QQ 官方机器人通道(合规接入)
群号设置
配群号- 回到主界面,打开 「AI回复设置」。
- 找到 「文字回复 AI(OpenAI 兼容接口)」,填三项:API Key、Base URL、模型 ID。
- 点 「测试连接」,成功后再保存。
- Base URL 留空表示使用智谱官方地址;换其他服务商时,填它提供的 OpenAI 兼容地址(一般以
/v1结尾)。模型示例:glm-4-flash、deepseek-chat、qwen-plus,按服务商文档填。
文字回复 AI(OpenAI 兼容接口)
可选官方通道发送安全:外链白名单、内容过滤、主动消息限频
外链域名白名单:回复内容含外链时,只允许已报备的域名。填域名本身,不带 https://,多个用英文逗号分隔,例如 api.example.com,img.example.com。留空表示不限制。
内容安全过滤:发送前对文本做敏感内容过滤,命中敏感词的回复不投递;敏感词表可在设置中编辑(每行一个,留空使用内置默认词表)。
群主动消息限频:范围 1–20 条/分钟/群,官方上限是单群 20 条/分钟。定时任务、报时、日报尽量错开分钟,避免堆在同一分钟被延迟或拦截。
改了 AppID 或 AppSecret 后,必须先「停止 Bot」再重新「启动 Bot」,新凭据才会生效。只保存不重启,客户端仍会用旧连接。
其他设置先不要动。先把聊天跑通,再慢慢开监控、语音、游戏等功能,排错会简单很多。
启动 Bot,再拉群
顺序最重要:客户端在线 → 拉机器人进群 → 群里 @ 它一次。
让机器人先上线,再进群
客户端不在线时拉群,客户端发现不到这个群
- 点主界面右下角的 「启动 Bot」。
- 等右上角状态变绿,并显示机器人名字。显示「未连接」时先不要拉群。
- 确认客户端在线后,再去 QQ 把机器人拉进群。
- 在群里 @机器人 发一句话,例如「你好」。收到回复就说明链路通了。
- 再私聊机器人发一句,确认私聊也能回复。
机器人早就在群里,也没人说话?让群主把机器人移出群,再重新拉进来,然后 @ 它一次。入群事件会触发客户端登记这个群;只等它自己发现,可能一直等不到。
状态一直是「未连接」:先检查 AppID / AppSecret 是否填对、网络是否正常、平台上的机器人是否可用;改过凭据的话,停止 Bot 再重新启动一次。
配群号:一次配对,之后只填群号
官方通道只给 32 位内部标识。配对之后,绝大多数按群设置都能直接用 QQ 群号。
把群和 QQ 群号对一次
设置 → 群号设置 → 配群号
- 打开 设置 → 群号设置,点 「配群号」。
- 弹窗里是机器人已经发现的群。官方群没有群名,所以每个群下方会显示 「最后一条」群消息,用它来认出这是哪个群。
- 点该群右侧的 「✏️ 群号」,填上它的 QQ 群号(只填数字),按回车或点确定;也可以按 「群号/备注」 一次填两个(如 81817586/我的群)。
- 显示变成 「群备注(81817586)」,就表示配对成功。已配对的群会变成绿色底。
- 想给群起个名字方便辨认,点 「✏️ 备注」 填文字保存(只在本机显示;随时可改可清除,不影响配对)。
- 要填多个群时,可以用搜索框过滤,或勾选「全选」;底部 「复制群号」 只复制勾选的群,没勾选时复制当前搜索出的全部群。
给机器人已发现的群填上 QQ 群号(一次配好),之后所有设置直接填群号。
演示区只在本页生效,不会改动客户端。实际操作时,群号/备注填完按回车即可。
群号没有在线查询。腾讯不提供「QQ 群号 → 内部标识」的映射,也不能反查。所以每个群只要手动配一次,配对关系保存在本机,重启不丢;配对表按 AppID 隔离,换机器人要重新配。
「✏️ 群号」里只认纯数字群号;文字备注请用 「✏️ 备注」单独填,方便辨认,不影响配对(群号框也支持「群号/备注」一次填两个,如 81817586/我的群)。每个群第一次出现时,日志会提醒一次「发现尚未配对群号的新群」,回来配一下即可。
保存分群设置时提示「尚未配对的 QQ 群号」,说明这个群号还没在「配群号」里填过。回到这里给对应群配一次,再保存就会通过。
- 分群回复概率:
81817586|100|30(群号 | 被 @ 概率 | 非 @ 概率) - 分群语音概率:
81817586|50;分群生图、菜单、附加提示词同理 - 题库、入群答题、精华关键词:题目行首写
81817586| - 分群欢迎语:
81817586:欢迎回家 - 定时消息、整点报时、日报:目标群直接填群号
设置主人(需要主人命令时再做)
官方通道里,主人身份是一串 32 位 openid,不是 QQ 号。需要让主人能远程开关功能时,才做这一步。
把主人的 openid 加进去
先让主人在群里 @ 机器人说一句话,再复制标识
- 先让主人本人(要设为主人的那个 QQ)在群里 @机器人 发一句话。
- 等几秒,按 Win + R,粘贴下面的路径回车,打开配置文件夹:
%APPDATA%\PaofuBot\identity_cache.json
- 用记事本打开 identity_cache.json,找到主人昵称对应的那一项,复制旁边那串 32 位 ID。
- 回到客户端:设置 → 主人设置,把 ID 粘贴进去(每行一个,可以填多个),保存。
- 主人在群里发「图片监控开启」「图片监控关闭」这类命令,就能远程控制开关。
identity_cache.json 含成员昵称与标识,属于个人信息。不要发到群里、不要截图外传。换 AppID 后 openid 会变,需要重新获取并更新主人设置。
备份与迁移(可选)
不是跑通必需的步骤,但配好群号、调完设置后建议导出一份。重装或换电脑时能省很多事。
导出一份配置备份
设置 → 配置备份 → 导出 / 导入
- 打开 设置 → 配置备份,点 「导出配置」,保存成 JSON 文件。
- 重装客户端或换电脑后,点 「导入配置」 选择这份 JSON,大部分业务与界面设置会立即恢复。
- 可同步的字段会自动推送到云端控制台。
账号凭据(AppID / AppSecret)与各类 API Key 属于敏感信息,不会导出。换电脑后需要手动重填这些凭据,再启动 Bot。
建议在「群号配对完成、AI 测试通过」之后导出一份,放到自己的网盘或移动硬盘。以后改乱了也能回滚。
哪些地方要填群号
记住一个前提:按群设置里的群号,必须先在「配群号」里填过一次。没配过的群号保存时会弹窗提醒,也不会生效。
| 想做什么 | 要填什么 | 示例 / 说明 |
|---|---|---|
| 只是聊天、用命令功能 | 不用填 | 默认对所有已发现的群生效 |
| 主人远程开关(群里发指令) | 主人 openid | 32 位标识,不是 QQ 号 |
| 定时消息、整点报时、日报只发指定群 | 群号 | 81817586(先配对) |
| 按群设置回复概率 | 行首群号 | 81817586|100|30 |
| 按群设置语音概率 | 行首群号 | 81817586|50 |
| 按群追加 AI 提示词 | 行首群号 | 81817586|说话简短一点 |
| 问一问、入群答题、精华关键词只对指定群生效 | 题目行首 | 81817586|题目内容 |
| 按群设置欢迎语 | 群号 + 冒号 | 81817586:欢迎回家 |
| 监控只监控指定群 | 不生效 | 官方通道默认全部监控,此白名单不生效 |
| 私聊机器人 | 不用填 | 私聊不需要群号 |
不确定某个功能填什么格式时,先在对应设置弹窗里看灰色提示文字;大多数输入框都支持「一行一个」,示例格式就写在提示里。
部署完成自查
逐项打勾。进度会保存在本机浏览器,下次打开还在。
7 项都通过,就算部署完成
建议重启一次客户端再核对最后两项
出问题先看这里
按报错码和现象整理。点标题展开处理办法。
空列表「配群号」里一个群都没有 / 拉取群 ID 是空的
说明客户端还没登记到群。按这个顺序排查:
- 确认客户端已经启动并且在线,再拉机器人进群。
- 进群后必须有人在群里 @机器人 发过一句话;只拉进群不说话,可能还没有事件。
- 机器人早就在群里:让群主移出群,再重新拉进来,然后 @ 一次。
- 点「配群号」里的「刷新」再看一次。
11255报错 11255,消息发不出去
通常是群已注销、机器人已经不在这个群,或群标识失效。重新把机器人拉进群,并在「配群号」里重新确认一次群号;如果这个群已经不存在,从定时/报时目标里删掉它。
11253报错 11253 是不是出问题了?
官方不提供群成员信息查询权限,报 11253 是正常现象,不影响聊天与回复。成员昵称会从群消息事件里自动积累,不需要额外处理。
401/403报 401 / 403,或一直未连接
AppID 或 AppSecret 填错,或者两者不属于同一个机器人,也可能是在平台上重置过密钥。重新从「开发设置」复制,回到「设置 → QQ 官方机器人通道」粘贴,保存后停止 Bot 再重新启动。
保存保存时提示「分群设置有误 / 尚未配对」
你填的某个 QQ 群号还没在「配群号」里配过。打开 设置 → 群号设置 → 配群号,给对应群填一次群号,再回来保存。已经配过的群号会放行,不会被拦。
不生效分群设置改了没反应
先看「配群号」里该行显示的是不是群号:
- 如果还是 32 位标识,说明没配对或配对到了别的群,重新配。
- 如果填的是文字备注而不是数字,说明只设了「✏️ 备注」,没有配群号——点「✏️ 群号」把数字群号填上。
- 确认保存成功,并且对应功能的开关、概率不为 0。
重启改了 AppID / AppSecret 没反应
保存不会自动重连。先点「停止 Bot」,再点「启动 Bot」。如果还是不行,确认平台上的机器人状态正常,并且填的是同一个机器人的一对凭据。
主人主人发指令没反应
主人设置里填错 ID 了。让主人先在群里 @机器人 发一句话,再从 %APPDATA%\PaofuBot\identity_cache.json 里复制 32 位 openid,粘贴到「设置 → 主人设置」。换过 AppID 的话,旧 openid 已失效,需要重新获取。
不回@ 了机器人但不回复
按顺序检查:
- AI 回复总开关是否打开,对应功能开关是否打开。
- AI 设置里点「测试连接」是否成功,Key 是否有余额。
- 「被 @ 时回复概率」是否为 0;概率调得太低时会经常不回复。
- 如果控制台日志有报错,先按报错码处理。
限频消息发不出去,或被延迟
官方限制单群主动消息最多 20 条/分钟。检查「官方通道发送安全 → 群主动消息限频」是否设得太低,以及定时、报时、日报是否都堆在同一分钟。错开发送时间即可。
回复里带外链时,还要确认域名在「消息外链域名白名单」里;没报备的链接会被拦截。
换机换电脑或重装后怎么恢复
在旧电脑上「设置 → 配置备份 → 导出配置」,把 JSON 带到新电脑导入。AppID / AppSecret 与 AI Key 不会导出,需要重新填写;如果换了 AppID,群号配对和主人 openid 也要重新做。
换群机器人被移出群,或换了新群
重新拉进群后 @ 一次,让客户端重新登记;新群第一次出现时日志会提示「发现尚未配对群号的新群」,去「配群号」补一次群号。被移出的旧群如果还在定时目标里,记得删掉。
最后几句提醒
之前所有群号配对、主人 openid 全部作废,需要重新配对和获取。
禁言、踢人等命令需要把机器人设为群管理员,并且受平台接口限制。
需要平台开通「全部群消息」权限;只有 @ 权限时,只能看到 @ 过机器人的消息。
AppSecret 和 AI Key 不要发群里、不要截图外传;换电脑要重新填。
单群最多 20 条/分钟。定时、报时、日报尽量错开分钟,避免被延迟或拦截。
V5 不适用。教程按 v6.1.3.9 编写,界面以客户端实际显示为准。