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

shangxue · 2025 年5 月 21 日 09:33

QQ 官方机器人接入教程（基于 Koishi）

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

本教程为论坛帖子【810 帖】的补充修订版本：QQ/QQ 频道登录指南

【QQ 开放平台 - 个人资格】

目前，个人创建群聊机器人的资格已面向所有用户开放。
在机器人后台创建新机器人后，系统将自动为其分配群聊使用权限。

实际效果展示

重要说明

本楼层内的提问将不予回复。如在操作中遇到问题，可加入 Koishi 用户交流群 ② 群咨询：
【948266958】正在跳转

Koishi 官方交流渠道汇总：参与讨论 | Koishi

特别提醒

本教程可确保在严格按步骤操作的前提下，100% 正常完成登录。

若你已完整阅读教程仍无法登录，请先查看【555 帖】排查问题：Koishi 用户交流群群规
并携带完整报错信息在交流群内提问。未看完教程提问、未提供四项完整报错信息即提问的用户，将被直接移出用户群，敬请留意。

其他接入方式说明

非官方接入方式（即使用普通 QQ 账号登录）不受任何官方支持，使用前请谨慎评估风险。

相关讨论请前往非官方社群：社区资源 | Koishi

shangxue · 2025 年5 月 21 日 09:36

开始之前……

注意事项

从现在开始，请严格按照本教程指引操作。

尤其需要注意：不要执行任何教程中未提及的操作。

根据过往反馈，大量用户因多选了 Intents 或开启了沙箱模式，最终导致机器人无法连接、无法接收消息等问题。

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

shangxue · 2025 年5 月 21 日 09:46

下载、安装与使用 Koishi

首先前往 Koishi 官方网站，下载并安装 Koishi。

如果你是初次使用 Koishi，推荐优先使用 Windows 版本。

请按照上述页面的安装教程完整操作，完成 Koishi 安装后，即可启动 Koishi。

启动 Koishi

你可以通过以下任意一种方式启动 Koishi：

双击桌面上的 Koishi 图标
在 Windows 开始菜单中搜索 koishi 并启动

更新 Koishi

启动 Koishi 后，按以下步骤更新至最新版本：

点击左侧栏的【依赖管理】
依次点击右上角的【火箭图标】与【勾号图标】，执行更新操作

注意，在这一步你可能会遇到【无法访问插件市场】等的问题 → 请参考此处 → 为什么我找不到downloads插件 - #4，来自 shangxue

安装成功后，Koishi 会自动重载一次。

接着，点击左侧栏的【插件市场】，搜索并安装 dialogue 插件，测试插件安装功能是否正常。

最后，点击左侧栏的【沙盒】，选择【添加用户】创建一个沙盒测试用户，在输入框输入 help 并发送，验证 Koishi 基础功能是否正常。

结论：若在沙盒中可正常与机器人对话，说明 Koishi 本体工作正常。

shangxue · 2025 年5 月 21 日 09:59

创建 QQ 机器人

前往 QQ 开放平台，注册账号并创建机器人账号。注意：注册入口在邮箱登录方式下。

若你已注册过该平台，可直接使用对应 QQ 账号扫码登录。

使用邮箱注册

screenshot_2026-07-21_18-12-20

邮箱注册成功后，腾讯平台会向你的邮箱发送激活邮件，内容如下：

你好，
感谢你注册QQ开放平台。
你的登录邮箱为：.....@...com。请点击以下链接激活账号（有效期为：此邮件发出后30分钟）

https://q.qq.com/mail/active?appType=0&....=1......

如果以上链接无法点击，请将上面的地址复制到你的浏览器地址栏进入QQ开放平台。

QQ开放平台团队

使用 QQ 账号扫码注册

直接使用 QQ 账号扫码，点击注册即可绑定当前 QQ 邮箱账号，如下图所示。

注册并登录 QQ 开放平台后，进入【机器人】页面（ QQ开放平台），点击【去创建或管理我的QQ机器人】按钮。

点击后将跳转至新标签页（ QQæºå¨äºº ），在此页面再次点击右上角的【创建机器人】按钮。

注意，必须为主体账号的管理员才能创建机器人，否则会出现提示【你不是主体账号的管理员，无法创建机器人】

创建完成后，机器人会自动添加为你的 QQ 好友，

并且开放平台页面将展示机器人 ID 与密钥。

请务必截图保存此页面，切勿关闭，以防密钥丢失。

至此，机器人注册完成。接下来需要进入机器人后台完成更多设置。

返回机器人列表页面（ QQ开放平台），完成【账号主体验证】。

验证完成后，再次返回机器人列表页面（ QQæºå¨äºº ），点击对应机器人。

点击页面左侧【开发管理】，在此处可获取四项关键数据：机器人 QQ 号、AppID、Token、AppSecret。请妥善记录并保管，切勿泄露。

结论：你已成功创建 QQ 机器人，并获取了对接所需的四项关键数据。

shangxue · 2025 年5 月 21 日 10:14

将 Koishi 对接机器人

决定机器人性质

在开始对接之前，你需要先确定机器人的类型：公域机器人或私域机器人。

机器人类型	流量策略
私域机器人	仅支持添加至自己创建的群组/频道，依靠白名单授权添加（必须账号主体为群主或管理员的群）。
公域机器人	支持搜索、推荐、添加到其他频道，任何人都可以添加进群。（个人主体上限500个群，企业主体无上限。）

在确定机器人类型后，请确保机器人设置与你期望的类型一致：
在左侧【沙箱配置】最下方的【机器人类型】处查看。

填写机器人信息

回到 Koishi，点击左侧栏的【插件配置】，在插件列表下方找到【adapter-qq】插件，依次填写所需数据。

注意：此处所需数据的顺序与机器人后台中显示的不同，请仔细对照后再填写。

本教程以个人主体的公域机器人为例进行讲解。

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

填写完成后，点击右上角的【保存】按钮。

接下来，滚动到下方的「intents」配置项：

如果你需要在 QQ 群中使用，勾选 USER_MESSAGE或GROUP_AND_C2C_EVENT(如果有)。
如果你需要在 QQ 频道的频道私信中使用，勾选 DIRECT_MESSAGES。
如果你需要在 QQ 频道中使用，且为公域机器人，勾选 PUBLIC_GUILD_MESSAGES。
请务必勾选 MESSAGE_AUDIT。

你也可以直接勾选除第三个和倒数第三个之外的全部选项。

关于其他配置项注意事项：

不要勾选「开启沙箱模式」

验证方式保持默认的 bearer 即可

注意：此处配置错误会直接导致机器人无法接入，填写时请务必仔细核对。

若遇到问题，可加入帖子最上方的用户交流群进行提问。

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

连接 QQ 官方机器人

最后，回到 Koishi 配置页面，点击右上角播放图标的【启动】按钮。插件会输出连接成功的日志，同时 Koishi 窗口右下角的状态指示灯会变为绿色。

结论：你已成功将 Koishi 与 QQ 机器人完成对接。

shangxue · 2025 年5 月 21 日 10:37

----------------------->分割线<-----------------------

shangxue · 2025 年5 月 21 日 10:44

步骤 ④

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

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

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

首先，将你的手机 QQ 升级至最新版（不低于 8.9.90），并在手 Q 内创建一个自己为群主的测试群（小于20人）。注意必须是群主身份。

在Q群设置里，可以找到【群机器人】选项，点进去之后点击【立即添加】

即可从你的消息列表里添加机器人。

现在，你已可以在 QQ 使用自己的机器人。输入【@】并选择机器人，然后在后面输入【status】并发送。你可以看到机器人正常工作。

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

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

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

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

之后，频道主可从沙箱频道“设置-机器人”打开机器人列表页添加测试机器人

现在，你已可以在 QQ 使用自己的机器人。输入【@】并选择机器人，然后在后面输入【status】并发送。你可以看到机器人正常工作。

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

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