泡芙Bot 部署教程
PaofuBot · Deployment Guide

泡芙Bot
部署与设置教程

从安装客户端,到机器人在群里回上第一句话。按顺序做完这 6 步,大约 10 分钟。本教程按最新 v6.1.3.9 编写,界面与文案以客户端实际显示为准。

Windows 10 / 11 · 64 位 约 10 分钟 6 个步骤 v6.1.3.9
6个部署步骤
2个关键设置
1次群号配对
10分钟跑通
Start Here

开始前,先记住三句话

这三条能避免 90% 的「拉了群却没反应」「群号填了不生效」。

RULE 01

群号只需配对一次

腾讯只给机器人一串 32 位内部标识,不提供 QQ 群号。第一次用「指定群」功能时,在「配群号」里把群和群号对一次,之后所有地方直接填群号。

RULE 02

顺序不能反

先启动客户端,再把机器人拉进群,最后在群里 @ 它一次。机器人靠群消息事件发现新群,顺序反了就会「拉取不到群」。

RULE 03

不指定群也能用

不填群号时,聊天、命令、监控、定时会对所有已发现的群生效。只有需要「只对某个群」生效时,才要配群号。

Overview

全流程一图看懂

前四步跑通基础聊天,第五步开始做「按群」配置。第一次部署建议按顺序走完。

1
安装登录客户端 + 会员
2
创建机器人拿 AppID / 密钥
3
填写设置官方通道 + AI
4
启动拉群先在线再拉群
5
配群号一次配对
6
设置主人群内远程开关

最容易被跳过的一步:拉群之前,客户端必须已经启动并显示在线;拉群之后,必须有人在群里 @ 机器人一次。两条都满足,客户端才能发现这个群。

Step 01

安装并登录客户端

装好、登录、确认会员状态。安装包已自带运行环境,不需要另外装 .NET。

01

装好客户端,能进主界面

Windows 10 / 11 · 64 位 · 需要管理员权限

安装包→ 一路下一步→ 登录 / 注册→ 主界面
  1. 双击 PaofuBot_v6.1.3.9_Setup.exe,按提示点「下一步」。安装需要管理员权限,默认装到 C:\Program Files\泡芙Bot,可以勾选创建桌面图标。
  2. 如果 Windows 弹出「已保护你的电脑」,先确认安装包来自你信任的渠道,再点「更多信息」→「仍要运行」。
  3. 打开客户端,注册或登录泡芙账号。注册需要收邮箱验证码,按页面提示填写即可。
  4. 如果提示「会员已过期」,点「充值 / 续费」完成后再重新登录。
  5. 看到主界面,就说明安装和登录都完成了。客户端之后会自动检查更新,收到提示按提示升级即可,不用反复重装。

安装路径、桌面图标都不影响后续配置。如果电脑装了多个用户账号,请固定用同一个 Windows 账号运行客户端,配置会保存在该用户的 %APPDATA%\PaofuBot 下。

Step 02

创建 QQ 官方机器人,拿到凭据

机器人要在 QQ 开放平台创建。你需要两样东西:AppID 和 AppSecret。

02

在 q.qq.com 创建机器人

开发设置 → AppID / AppSecret → 按需提交上线

q.qq.com→ 创建机器人→ 开发设置→ 复制 AppID / AppSecret
  1. 浏览器打开 q.qq.com(QQ 开放平台),用 QQ 登录。
  2. 创建一个机器人,按平台要求填写资料。个人还是企业主体,按你的实际情况选择。
  3. 进入「开发设置」,复制 AppID 和 AppSecret。AppSecret 通常只完整显示一次,先存到安全的地方。
  4. 开发阶段的机器人只能在自己有管理权限的测试群里使用;要给客户群用,按平台流程提交上线。

一个 AppID 就是一个机器人身份。换 AppID 等于换了一个机器人:之前的群号配对、主人设置全部作废,需要重新配。确定好用哪个机器人再开始。

官方通道默认只能收到「群内 @机器人」和「私聊」消息。未 @ 的普通群消息需要平台开通「全部群消息」权限;群管、监控等能力也受平台接口限制,具体以平台返回为准。

Step 03

只填两个关键设置

先让「官方通道」和「AI 回复」跑通,其他开关暂时不用动。

03

官方通道 + AI 回复

主界面右下角「设置」;AI 设置在主界面的「AI回复设置」

主界面→ 设置→ QQ 官方机器人通道 + AI回复设置
1. 打开「设置」,填官方通道
  1. 点主界面右下角的 「设置」。
  2. 找到 「QQ 官方机器人通道(合规接入)」,勾选开关。
  3. 填入刚复制的 AppID 和 AppSecret。
  4. 点 「保存设置」。AppSecret 只保存在本机,不会上云。
设置 界面示意

QQ 官方机器人通道(合规接入)

AppID
1029 **** ****
AppSecret
••••••••••••••••

群号设置

配群号
监控群(官方通道默认全部监控)
每行一个群号,配好群号后再填
取消 保存设置
2. 打开「AI回复设置」,填 AI 接口
  1. 回到主界面,打开 「AI回复设置」。
  2. 找到 「文字回复 AI(OpenAI 兼容接口)」,填三项:API Key、Base URL、模型 ID。
  3. 点 「测试连接」,成功后再保存。
  4. Base URL 留空表示使用智谱官方地址;换其他服务商时,填它提供的 OpenAI 兼容地址(一般以 /v1 结尾)。模型示例:glm-4-flash、deepseek-chat、qwen-plus,按服务商文档填。
AI 回复设置 界面示意 · 可点击测试

文字回复 AI(OpenAI 兼容接口)

API Key
sk-••••••••••••••••
Base URL(留空使用智谱官方)
https://open.bigmodel.cn/api/paas/v4
模型 ID
glm-4-flash
三项填完,先测试再保存
演示按钮只在本页生效,不会改动客户端设置。
可选官方通道发送安全:外链白名单、内容过滤、主动消息限频

外链域名白名单:回复内容含外链时,只允许已报备的域名。填域名本身,不带 https://,多个用英文逗号分隔,例如 api.example.com,img.example.com。留空表示不限制。

内容安全过滤:发送前对文本做敏感内容过滤,命中敏感词的回复不投递;敏感词表可在设置中编辑(每行一个,留空使用内置默认词表)。

群主动消息限频:范围 1–20 条/分钟/群,官方上限是单群 20 条/分钟。定时任务、报时、日报尽量错开分钟,避免堆在同一分钟被延迟或拦截。

改了 AppID 或 AppSecret 后,必须先「停止 Bot」再重新「启动 Bot」,新凭据才会生效。只保存不重启,客户端仍会用旧连接。

其他设置先不要动。先把聊天跑通,再慢慢开监控、语音、游戏等功能,排错会简单很多。

Step 04

启动 Bot,再拉群

顺序最重要:客户端在线 → 拉机器人进群 → 群里 @ 它一次。

04

让机器人先上线,再进群

客户端不在线时拉群,客户端发现不到这个群

启动 Bot→ 确认右上角变绿→ 把机器人拉进群→ 群里 @ 一次
  1. 点主界面右下角的 「启动 Bot」。
  2. 等右上角状态变绿,并显示机器人名字。显示「未连接」时先不要拉群。
  3. 确认客户端在线后,再去 QQ 把机器人拉进群。
  4. 在群里 @机器人 发一句话,例如「你好」。收到回复就说明链路通了。
  5. 再私聊机器人发一句,确认私聊也能回复。

机器人早就在群里,也没人说话?让群主把机器人移出群,再重新拉进来,然后 @ 它一次。入群事件会触发客户端登记这个群;只等它自己发现,可能一直等不到。

状态一直是「未连接」:先检查 AppID / AppSecret 是否填对、网络是否正常、平台上的机器人是否可用;改过凭据的话,停止 Bot 再重新启动一次。

Step 05 · Core

配群号:一次配对,之后只填群号

官方通道只给 32 位内部标识。配对之后,绝大多数按群设置都能直接用 QQ 群号。

05

把群和 QQ 群号对一次

设置 → 群号设置 → 配群号

设置→ 群号设置→ 配群号→ ✏️ 群号→ 填群号,回车
  1. 打开 设置 → 群号设置,点 「配群号」。
  2. 弹窗里是机器人已经发现的群。官方群没有群名,所以每个群下方会显示 「最后一条」群消息,用它来认出这是哪个群。
  3. 点该群右侧的 「✏️ 群号」,填上它的 QQ 群号(只填数字),按回车或点确定;也可以按 「群号/备注」 一次填两个(如 81817586/我的群)。
  4. 显示变成 「群备注(81817586)」,就表示配对成功。已配对的群会变成绿色底。
  5. 想给群起个名字方便辨认,点 「✏️ 备注」 填文字保存(只在本机显示;随时可改可清除,不影响配对)。
  6. 要填多个群时,可以用搜索框过滤,或勾选「全选」;底部 「复制群号」 只复制勾选的群,没勾选时复制当前搜索出的全部群。
配群号 界面示意 · 可点击试填

给机器人已发现的群填上 QQ 群号(一次配好),之后所有设置直接填群号。

群 A A0E98CC7…B788D
未配群号
最后一条:小明:今晚开黑吗?(21:04)
群 B B7C1D2…9F3A
未配群号
最后一条:群主:公告已更新,记得看群文件(18:22)
复制群号 插入群号

演示区只在本页生效,不会改动客户端。实际操作时,群号/备注填完按回车即可。

群号没有在线查询。腾讯不提供「QQ 群号 → 内部标识」的映射,也不能反查。所以每个群只要手动配一次,配对关系保存在本机,重启不丢;配对表按 AppID 隔离,换机器人要重新配。

「✏️ 群号」里只认纯数字群号;文字备注请用 「✏️ 备注」单独填,方便辨认,不影响配对(群号框也支持「群号/备注」一次填两个,如 81817586/我的群)。每个群第一次出现时,日志会提醒一次「发现尚未配对群号的新群」,回来配一下即可。

保存分群设置时提示「尚未配对的 QQ 群号」,说明这个群号还没在「配群号」里填过。回到这里给对应群配一次,再保存就会通过。

配对之后,这些地方可以直接填群号
  • 分群回复概率:81817586|100|30(群号 | 被 @ 概率 | 非 @ 概率)
  • 分群语音概率:81817586|50;分群生图、菜单、附加提示词同理
  • 题库、入群答题、精华关键词:题目行首写 81817586|
  • 分群欢迎语:81817586:欢迎回家
  • 定时消息、整点报时、日报:目标群直接填群号
Step 06

设置主人(需要主人命令时再做)

官方通道里,主人身份是一串 32 位 openid,不是 QQ 号。需要让主人能远程开关功能时,才做这一步。

06

把主人的 openid 加进去

先让主人在群里 @ 机器人说一句话,再复制标识

主人群里 @ 一次→ 打开 identity_cache.json→ 复制 32 位 ID→ 主人设置
  1. 先让主人本人(要设为主人的那个 QQ)在群里 @机器人 发一句话。
  2. 等几秒,按 Win + R,粘贴下面的路径回车,打开配置文件夹:
%APPDATA%\PaofuBot\identity_cache.json
  1. 用记事本打开 identity_cache.json,找到主人昵称对应的那一项,复制旁边那串 32 位 ID。
  2. 回到客户端:设置 → 主人设置,把 ID 粘贴进去(每行一个,可以填多个),保存。
  3. 主人在群里发「图片监控开启」「图片监控关闭」这类命令,就能远程控制开关。

identity_cache.json 含成员昵称与标识,属于个人信息。不要发到群里、不要截图外传。换 AppID 后 openid 会变,需要重新获取并更新主人设置。

Bonus · Optional

备份与迁移(可选)

不是跑通必需的步骤,但配好群号、调完设置后建议导出一份。重装或换电脑时能省很多事。

+

导出一份配置备份

设置 → 配置备份 → 导出 / 导入

设置→ 配置备份→ 导出配置→ 保存 JSON
  1. 打开 设置 → 配置备份,点 「导出配置」,保存成 JSON 文件。
  2. 重装客户端或换电脑后,点 「导入配置」 选择这份 JSON,大部分业务与界面设置会立即恢复。
  3. 可同步的字段会自动推送到云端控制台。

账号凭据(AppID / AppSecret)与各类 API Key 属于敏感信息,不会导出。换电脑后需要手动重填这些凭据,再启动 Bot。

建议在「群号配对完成、AI 测试通过」之后导出一份,放到自己的网盘或移动硬盘。以后改乱了也能回滚。

Reference

哪些地方要填群号

记住一个前提:按群设置里的群号,必须先在「配群号」里填过一次。没配过的群号保存时会弹窗提醒,也不会生效。

想做什么要填什么示例 / 说明
只是聊天、用命令功能 不用填 默认对所有已发现的群生效
主人远程开关(群里发指令) 主人 openid 32 位标识,不是 QQ 号
定时消息、整点报时、日报只发指定群 群号 81817586(先配对)
按群设置回复概率 行首群号 81817586|100|30
按群设置语音概率 行首群号 81817586|50
按群追加 AI 提示词 行首群号 81817586|说话简短一点
问一问、入群答题、精华关键词只对指定群生效 题目行首 81817586|题目内容
按群设置欢迎语 群号 + 冒号 81817586:欢迎回家
监控只监控指定群 不生效 官方通道默认全部监控,此白名单不生效
私聊机器人 不用填 私聊不需要群号

不确定某个功能填什么格式时,先在对应设置弹窗里看灰色提示文字;大多数输入框都支持「一行一个」,示例格式就写在提示里。

Checklist

部署完成自查

逐项打勾。进度会保存在本机浏览器,下次打开还在。

7 项都通过,就算部署完成

建议重启一次客户端再核对最后两项

0/7
进度仅保存在本机浏览器,不会上传。
Troubleshooting

出问题先看这里

按报错码和现象整理。点标题展开处理办法。

空列表「配群号」里一个群都没有 / 拉取群 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 也要重新做。

换群机器人被移出群,或换了新群

重新拉进群后 @ 一次,让客户端重新登记;新群第一次出现时日志会提示「发现尚未配对群号的新群」,去「配群号」补一次群号。被移出的旧群如果还在定时目标里,记得删掉。

Notes

最后几句提醒

换 AppID = 换身份

之前所有群号配对、主人 openid 全部作废,需要重新配对和获取。

群管功能需要管理员

禁言、踢人等命令需要把机器人设为群管理员,并且受平台接口限制。

监控依赖消息权限

需要平台开通「全部群消息」权限;只有 @ 权限时,只能看到 @ 过机器人的消息。

密钥只留在本机

AppSecret 和 AI Key 不要发群里、不要截图外传;换电脑要重新填。

主动消息有上限

单群最多 20 条/分钟。定时、报时、日报尽量错开分钟,避免被延迟或拦截。

教程适用版本 v6 以上

V5 不适用。教程按 v6.1.3.9 编写,界面以客户端实际显示为准。