QQ/QQ 频道登录指南（布丁）

shangxue · 2025 年5 月 21 日 09:33

本将引导你使用 Koishi 通过QQ开放平台，实现接入 QQ 和 QQ 频道，搭建QQ官方机器人。

本教程为 810帖的布丁版本（更多糖？）

■ QQ开放平台 - 个人资格 ■

目前个人创建群聊机器人的资格已面向所有用户开放。

在机器人后台创建新的机器人后，机器人会自动获得群聊权限。

实际效果展示

注意：在本楼内进行提问将不会得到回复。请前往对应时间的帖子进行提问。

警告：近期用户群内由于不看教程导致的无法登录的例子明显增多，无法登录的情况无一例外是由于没有认真按本教程操作所致。

在这里再次强调：本教程可以保证 100% 的情况正常登录，但你必须严格按照教程操作。

如果你确信自己读完了整篇教程仍无法登录的话，查看 555帖并携带全部的报错信息在群内提问。没有看完教程就提问的、没有发四项报错信息就提问的将会被直接踢出用户群，请注意。

如果遇到任何问题，你都可以加入 Koishi 用户交流群 ② 群：948266958 提问。

加入 Koishi 用户交流群进行讨论 → 参与讨论 | Koishi

寻找其他的接入方式？

非官方接入方法不被任何官方支持，请务必慎重考虑。

请前往非官方社群进行讨论 → 社区资源 | Koishi

shangxue · 2025 年5 月 21 日 09:36

开始之前……

需要注意

从现在开始，需要严格按照本贴的指导操作。

尤其注意不要做教程没有指导的事情。

阅读本教程的用户有相当大的比例多选了 `intents` 或 `打开了sandbox` ，最终导致机器人无法连接或无法收到消息。

请严格按照本贴的指导操作，不要多做或漏做步骤。
如果你没有严格按照本贴操作而无法对接到 QQ 平台，这种情况下在用户群提问，可能被直接踢出，请一定注意。
在对接没有成功时，请先认真阅读本贴内容，检查自己是否做错了步骤。

需要决定

你需要先确定这两件事——

1. 你的身份：是个人还是企业？

企业需要你自己有个体户身份，或有一个正在运营的公司。
个人身份不需要任何条件。

2. 机器人的使用范围类型：是全量还是白名单？

如果创建全量机器人，那么你的机器人将可以被任何人添加到任何群。
如果创建白名单机器人，只有你能够指定机器人添加的群。

shangxue · 2025 年5 月 21 日 09:46

步骤 ①

下载、安装和使用 Koishi

先前往 Koishi 的官网下载并安装 Koishi。

如果你是第一次接触 Koishi，我们推荐使用 Koishi 的 Windows 版本。

根据为 Windows 安装 | Koishi 引导的安装教程完整操作完成安装 koishi 之后，我们应该就可以启动 koishi 了。

启动 koishi

像任何软件一样，点击 koishi 的桌面图标，即可启动 koishi

在Windows菜单里搜索koishi，并启动

更新 koishi

启动 Koishi 后，先点击左侧栏的「依赖管理」，之后点击右上角的「火箭」按钮和「勾号」按钮，将 Koishi 更新至最新版本。

安装成功后 koishi会自动重载一次

接着，点击左侧活动栏的「插件市场」图标，搜索并安装 `dialogue` 插件，测试能否正常安装新的插件。

最后，点击左侧活动栏的「沙盒」，点击「添加用户」以创建一个沙盒用户，在输入框键入「help」并发送，以测试 Koishi 本身的功能是否正常。

结论：Koishi 本体正常工作，在沙盒中能够正常与 Koishi 机器人对话。

shangxue · 2025 年5 月 21 日 09:59

步骤 ②

创建 QQ 机器人

前往 QQ 开放平台，注册一个账号。

注册账号并登录 QQ 开放平台后，前往「应用管理」点击「创建机器人」按钮。

输入机器人的基本信息后点击「下一步」。

之后，选择机器人的类型，最后点击「创建」。

成功创建机器人后即可进入机器人后台。

点击页面左侧的「开发管理」。在这里，你可以得到四项数据：机器人 QQ 号、AppID、Token 和 AppSecret。记下这些数据，并且千万不要泄漏它们。

结论：你创建了自己的 QQ 机器人，获得了四项数据。

shangxue · 2025 年5 月 21 日 10:14

步骤 ③

将 Koishi 对接机器人

回到 Koishi，点击左侧栏的「插件配置」，翻到插件列表的下方找到「adapter-qq」插件。分别填写需要的数据。

注意此处数据的需求和顺序都和上文机器人后台中的不相同，请仔细对照后填写。

之后，在机器人类型（`type`）配置项选择公域（`public`）。

填写完毕后，点击右上角的「保存」按钮。

接下来，翻到下方的「intents」配置项。

如果你准备在 QQ 群中使用，勾选 USER_MESSAGE。
如果你准备在 QQ 频道的 频道私信 列表中使用，勾选 DIRECT_MESSAGES。
如果你准备在 QQ 频道中使用，且你的机器人是公域机器人，勾选 PUBLIC_GUILD_MESSAGES。
勾选 MESSAGE_AUDIT。

注意此处若填写错误将会直接导致机器人无法接入。填写时请务必仔细。

如果遇到问题，可以加入帖子最上方的用户交流群提问。

假如你全部都想要订阅，可以参考：

填写完毕后，点击右上角的「保存」按钮。

连接QQ官方机器人

接下来，我们需要找一个IPV4检测网站

比如 → 我的公网 IP 地址 - 锤子在线工具

使用你需要登录机器人的机器，访问此网址。即可得到你的公网IPV4地址了。

接下来我们需要将此IP地址，配置到QQ开放平台后台的IP白名单内

前往 → QQ机器人管理端 QQ开放平台，点击左侧的【开发管理】，找到其中的【IP白名单】配置项

将你复制到的IPV4地址配置到其中

出现【保存成功】的提示即代表配置生效

最后，回到koishi配置项处，点击右上角播放图标的「启动」按钮。插件会输出一条成功连接的日志，同时，Koishi 窗口的右下角已点亮绿灯。

结论：你成功将 Koishi 对接了 QQ 机器人。

shangxue · 2025 年5 月 21 日 10:37

将机器人拉入测试群/测试频道

你可以选择在 QQ 群或 QQ 频道中测试你的机器人。

在 QQ 群中测试（点击展开）

首先，将你的手机 QQ 升级至最新版（不低于 8.9.90），并在手 Q 内创建一个自己为群主的测试群。

之后，回到 QQ 机器人的网页后台，点击左侧的「沙箱配置」，翻到页面最下方，在「在 QQ 群配置」一栏选择刚刚创建的测试群。

接着，在手 Q 中打开测试群，点击右上角的菜单图标，向下翻动找到「群机器人」选项，进入并添加刚刚创建的机器人。现在，你已可以在 QQ 使用自己的机器人。输入「@」并选择机器人，然后在后面输入「help」并发送。你可以看到机器人正常工作。

结论：你已将自己的机器人拉入测试群，并能够正常使用机器人。

恭喜，你刚刚创建了自己的机器人。

在 QQ 频道中测试（点击展开）

首先，将你的手机 QQ 升级至最新版（不低于 8.9.90），并在手 Q 内创建一个自己为频道主的测试频道。

之后，回到 QQ 机器人的网页后台，点击左侧的「沙箱配置」，在最上方的「在 QQ 频道配置」一栏选择刚刚创建的测试频道。

接着，在手 Q 中打开测试频道，在频道列表区域，点击最上方的 Header 大卡（背景图），点击「机器人」，翻到页面最底部并添加刚刚创建的机器人。现在，你已可以在 QQ 使用自己的机器人。输入「@」并选择机器人，然后在后面输入「help」并发送。你可以看到机器人正常工作。

结论：你已将自己的机器人拉入测试频道，并能够正常使用机器人。

shangxue · 2025 年5 月 21 日 10:50

后续 ①

配置斜杠指令

QQ 机器人的斜杠指令功能使你可以直接点选需要使用的指令，而无需手动输入。

首先，在 Koishi 中点击左侧栏的「插件配置」，接着选择插件列表中最上方的「全局配置」。

向下翻动到「prefix」配置项，并按照图中填写。第一项为「/」，第二项不填。

这使得你的机器人在带斜杠和不带斜杠的情况下都能正确触发指令。

最后，点击右上角的「对勾」图标，会自动重载 Koishi。

接下来，回到 QQ 机器人后台，点击左侧的「功能配置」，然后点击右侧的「配置」按钮。

选择「指令」选项卡，点击右上角的「配置」，并在这里配置机器人的可用指令。

推荐至少配置4到5个普通指令。避免新闻类、AI类、低俗类、迷信类等功能。初期建议配置一点简单的图文功能。

配置完毕后，点击「保存」。现在，你已经可以使用斜杠指令。

结论：你已在 Koishi 中正确配置斜杠指令支持，并在 QQ 机器人后台添加了可用指令。

shangxue · 2025 年5 月 21 日 11:03

后续 ②

提测与上线

机器人准备完毕后，你可以开始进行提测与上线步骤。

在提测前，你应当完成上方的「配置斜杠指令」步骤，并确保你的机器人已经有可用的指令。

打开 QQ 机器人后台，点击左侧的「发布设置」，然后点击「自测报告」内的「下载模板」，下载一份自测报告模板。

自测报告 - 示例

隐私协议 - 示例

仅需修改标黄的文字部分，模板内容以你在QQ开放平台下载的最新模板为准。此处仅供示例。

image2224×1226 158 KB

认真自测并填写此模板。自测完毕后，上传自测报告，并点击「上线机器人」。腾讯将会人工审核你的机器人，并准许上线。

在审核通过，并且点击【确认上线】后，你的机器人就可以被其他QQ群和用户添加了！

结论：你已提测机器人。

shangxue · 2025 年5 月 21 日 11:04

遇到问题

如果你遇到问题，你应当首先收集与问题有关的全部信息。

「Koishi 用户交流群群规」贴中给出了收集信息的方法：

收集信息后，翻阅下方的讨论，查找是否有与你的问题相同的问题，并按照解决方法操作。

如果没有找到相同的问题，那么你现在可以带上全部的信息回帖。

ilharp · 2025 年5 月 21 日 13:11

我就要翻

itzdrli · 2025 年5 月 21 日 15:54

不需要再向下翻动。下方已没有更多内容。

StarFreedomX · 2025 年6 月 19 日 04:16

不需要再向下翻动。下方已没有更多内容。

magisk317 · 2025 年7 月 12 日 03:27

这个ip，在其他地方还能看到吗？比如log里，我这里网络环境比较复杂，一方面是公司网，另一方面是docker+远程+梯子，不管内网外网，添加了十几个ip了都不对，有什么办法能获取到qq那边获取到的具体是哪个ip吗？

shangxue · 2025 年7 月 12 日 05:37

应该有专门测出口IP的网站吧

我觉得这样的网络布局最后搭建出来的机器人，延迟会比较高

ilharp · 2025 年7 月 12 日 13:44

下载安装启动 ipinfo 插件，插件给出的结果就是需要填写的 IP 了。

但即使这种方法也不会保证可用，某些公司会买一组 IP 然后随机分配，这种情况下基本没有办法（除非把公司的所有 IP 全部填进去）。

windbullet · 2025 年7 月 13 日 01:24

从0.0.0.0到255.255.255.255都填上去

magisk317 · 2025 年7 月 13 日 15:13

文中不就有网站，主要问题是我现在是ssh远程，没办法开浏览器，用命令测出来的又不准（比如类似curl ipinfo.io/ip那种），难搞

其实还好

magisk317 · 2025 年7 月 13 日 15:14

真快了。。。我把各种方式得到的都填上去了，还是不行

magisk317 · 2025 年7 月 13 日 15:17

你是说机器人插件吗？方便甩个链接嘛？搜到了两个不知道是不是

我司确实是这样的，大家都在同一网段，都是10.33.xx.xx，基本都是最后一段不一样，但是这是内网，出口ip应该比较固定，只有一个或者几个，但是现在不在公司，要不然顺手就测了哈哈哈

QQ/QQ 频道 登录指南 （布丁）

本将引导你使用 Koishi 通过QQ开放平台，实现接入 QQ 和 QQ 频道，搭建QQ官方机器人。

■ QQ开放平台 - 个人资格 ■

目前 个人创建群聊机器人的资格 已面向所有用户开放。

在机器人后台 创建新的机器人 后，机器人会自动获得群聊权限。

注意：在本楼内进行提问将不会得到回复。请前往对应时间的帖子进行提问。

警告：近期用户群内由于不看教程导致的无法登录的例子明显增多，无法登录的情况无一例外是由于没有认真按本教程操作所致。

在这里再次强调：本教程可以保证 100% 的情况正常登录，但你必须严格按照教程操作。

如果你确信自己读完了整篇教程仍无法登录的话，查看 555帖 并携带全部的报错信息在群内提问。没有看完教程就提问的、没有发四项报错信息就提问的将会被直接踢出用户群，请注意。

如果遇到任何问题，你都可以加入 Koishi 用户交流群 ② 群：948266958 提问。

加入 Koishi 用户交流群进行讨论 → 参与讨论 | Koishi

寻找其他的接入方式？

请前往 非官方社群 进行讨论 → 社区资源 | Koishi

开始之前……

需要注意

从现在开始，需要严格按照本贴的指导操作。

尤其注意 不要做教程没有指导的事情。

阅读本教程的用户有相当大的比例多选了 intents 或 打开了sandbox ，最终导致机器人无法连接或无法收到消息。

需要决定

你需要先确定这两件事——

1. 你的身份：是 个人 还是 企业？

2. 机器人的使用范围类型：是 全量 还是 白名单？

下载、安装和使用 Koishi

先前往 Koishi 的官网下载并安装 Koishi。

如果你是第一次接触 Koishi，我们推荐使用 Koishi 的 Windows 版本。

根据 为 Windows 安装 | Koishi 引导的安装教程 完整操作 完成安装 koishi 之后，我们应该就可以启动 koishi 了。

启动 koishi

像任何软件一样，点击 koishi 的桌面图标，即可启动 koishi

在Windows菜单里搜索koishi，并启动

更新 koishi

启动 Koishi 后，先点击左侧栏的「依赖管理」，之后点击右上角的「火箭」按钮和「勾号」按钮，将 Koishi 更新至最新版本。

接着，点击左侧活动栏的「插件市场」图标，搜索并安装 dialogue 插件，测试能否正常安装新的插件。

最后，点击左侧活动栏的「沙盒」，点击「添加用户」以创建一个沙盒用户，在输入框键入「help」并发送，以测试 Koishi 本身的功能是否正常。

结论：Koishi 本体正常工作，在沙盒中能够正常与 Koishi 机器人对话。

创建 QQ 机器人

前往 QQ 开放平台，注册一个账号。

注册账号并登录 QQ 开放平台后，前往「应用管理」 点击「创建机器人」按钮。

输入机器人的基本信息后点击「下一步」。

之后，选择机器人的类型，最后点击「创建」。

成功创建机器人后即可进入机器人后台。

点击页面左侧的「开发管理」。在这里，你可以得到 四项数据：机器人 QQ 号、AppID、Token 和 AppSecret。记下这些数据，并且千万不要泄漏它们。

结论：你创建了自己的 QQ 机器人，获得了四项数据。

将 Koishi 对接机器人

回到 Koishi，点击左侧栏的「插件配置」，翻到插件列表的下方找到「adapter-qq」插件。分别填写需要的数据。

注意此处数据的需求和顺序都和上文机器人后台中的不相同，请仔细对照后填写。

之后，在 机器人类型 （type）配置项 选择公域（public）。

填写完毕后，点击右上角的「保存」按钮。

接下来，翻到下方的「intents」配置项。

注意此处若填写错误将会直接导致机器人无法接入。填写时请务必仔细。

如果遇到问题，可以加入帖子最上方的用户交流群提问。

填写完毕后，点击右上角的「保存」按钮。

连接QQ官方机器人

接下来，我们需要找一个IPV4检测网站

比如 → 我的公网 IP 地址 - 锤子在线工具

使用你需要登录机器人的机器，访问此网址。即可得到你的公网IPV4地址了。

接下来 我们需要将此IP地址，配置到QQ开放平台后台的IP白名单内

前往 → QQ机器人管理端 QQ开放平台，点击左侧的【开发管理】，找到其中的【IP白名单】配置项

将你复制到的IPV4地址 配置到其中

出现【保存成功】的提示 即代表配置生效

最后，回到koishi配置项处，点击右上角播放图标的「启动」按钮。插件会输出一条成功连接的日志，同时，Koishi 窗口的右下角已点亮绿灯。

结论：你成功将 Koishi 对接了 QQ 机器人。

更多连接协议

将机器人拉入测试群/测试频道

配置斜杠指令

QQ 机器人的斜杠指令功能使你可以直接点选需要使用的指令，而无需手动输入。

首先，在 Koishi 中点击左侧栏的「插件配置」，接着选择插件列表中最上方的「全局配置」。

向下翻动到「prefix」配置项，并按照图中填写。第一项为「/」，第二项不填。

这使得你的机器人在 带斜杠和不带斜杠的情况下 都能正确触发指令。

最后，点击右上角的「对勾」图标，会自动重载 Koishi。

接下来，回到 QQ 机器人后台，点击左侧的「功能配置」，然后点击右侧的「配置」按钮。

选择「指令」选项卡，点击右上角的「配置」，并在这里配置机器人的可用指令。

推荐至少配置4到5个普通指令。避免新闻类、AI类、低俗类、迷信类 等功能。初期建议配置一点简单的图文功能。

配置完毕后，点击「保存」。现在，你已经可以使用斜杠指令。

结论：你已在 Koishi 中正确配置斜杠指令支持，并在 QQ 机器人后台添加了可用指令。

提测与上线

机器人准备完毕后，你可以开始进行提测与上线步骤。

在提测前，你应当完成上方的「配置斜杠指令」步骤，并确保你的机器人已经有可用的指令。

打开 QQ 机器人后台，点击左侧的「发布设置」，然后点击「自测报告」内的「下载模板」，下载一份自测报告模板。

认真自测并填写此模板。自测完毕后，上传自测报告，并点击「上线机器人」。腾讯将会人工审核你的机器人，并准许上线。

在审核通过，并且点击【确认上线】后，你的机器人就可以被其他QQ群和用户添加了！

QQ/QQ 频道登录指南（布丁）

目前个人创建群聊机器人的资格已面向所有用户开放。

在机器人后台创建新的机器人后，机器人会自动获得群聊权限。

如果你确信自己读完了整篇教程仍无法登录的话，查看 555帖并携带全部的报错信息在群内提问。没有看完教程就提问的、没有发四项报错信息就提问的将会被直接踢出用户群，请注意。

请前往非官方社群进行讨论 → 社区资源 | Koishi

尤其注意不要做教程没有指导的事情。

阅读本教程的用户有相当大的比例多选了 `intents` 或 `打开了sandbox` ，最终导致机器人无法连接或无法收到消息。

1. 你的身份：是个人还是企业？

2. 机器人的使用范围类型：是全量还是白名单？

根据为 Windows 安装 | Koishi 引导的安装教程完整操作完成安装 koishi 之后，我们应该就可以启动 koishi 了。

接着，点击左侧活动栏的「插件市场」图标，搜索并安装 `dialogue` 插件，测试能否正常安装新的插件。

注册账号并登录 QQ 开放平台后，前往「应用管理」点击「创建机器人」按钮。

点击页面左侧的「开发管理」。在这里，你可以得到四项数据：机器人 QQ 号、AppID、Token 和 AppSecret。记下这些数据，并且千万不要泄漏它们。

之后，在机器人类型（`type`）配置项选择公域（`public`）。

接下来我们需要将此IP地址，配置到QQ开放平台后台的IP白名单内

将你复制到的IPV4地址配置到其中

出现【保存成功】的提示即代表配置生效

这使得你的机器人在带斜杠和不带斜杠的情况下都能正确触发指令。

推荐至少配置4到5个普通指令。避免新闻类、AI类、低俗类、迷信类等功能。初期建议配置一点简单的图文功能。

「Koishi 用户交流群群规」贴中给出了收集信息的方法：