本文档将详细介绍如何使用 Koishi 框架接入 QQ 及 QQ 频道平台，为开发者提供从环境搭建到机器人上线的完整流程。

企业用户支持

企业用户可添加 Koishi 官方客服 QQ：2953529126↗ ，获取一对一专属技术支持与接入指导。客服工作时间：工作日 9:00-18:00。

个人用户资格说明

自2024年起，QQ开放平台已面向所有用户开放个人群聊机器人创建资格。创建机器人后将自动获得群聊消息接收权限，无需额外申请。在机器人后台 创建新的机器人 后，机器人会自动获得群聊权限。遇到任何问题都可以在 Koishi 官网的 参与讨论↗ 页中加入 Koishi 用户交流群进行讨论。

开始之前……

重要操作须知

常见错误包括：多选不必要的 消息事件权限 权限、误启用沙箱模式、配置顺序错误等。若未按教程操作导致接入失败，技术支持可能无法及时响应。建议操作前完整阅读对应章节，确保每一步配置正确。

接入前准备

在开始接入前，请确认以下信息：

账号类型选择

• 个人账号: 无需资质，适合个人开发者和非商业用途
• 企业账号: 需提供营业执照/个体户证明，适合商业应用场景

机器人可见范围

• 全量机器人: 可被任何用户添加至群聊/频道，需通过腾讯内容安全审核
• 白名单机器人: 仅可添加至指定群聊/频道，适合内部测试或私有部署场景，无需通过内容安全审核。

教程步骤

下载、安装和使用 Koishi

环境准备

1. 访问 Koishi 官网↗ 下载对应系统版本（Windows/macOS/Linux）
2. 安装完成后启动 Koishi，首次启动将自动安装依赖环境
3. 点击左侧「依赖管理」→ 右上角「火箭图标」更新至最新版本

注意：Windows 用户需确保已安装 Node.js 16+↗ 和 Git↗，macOS 用户建议通过 Homebrew 安装依赖

Koishi

创建跨平台、可扩展、高性能的机器人

前往 Koishi

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

创建 QQ 机器人

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

如果准备以企业身份注册账号，请阅读 文档↗ 以了解如何使用对公账户完成企业认证。如果遇到问题，可以通过帖子最上方的企业绿色通道联系 Koishi 客服。

注册账号并登录 QQ 开放平台后，点击页面右侧的「创建机器人」。输入机器人的基本信息后点击「下一步」。之后，选择机器人的类型，最后点击「创建」。

成功创建机器人后即可进入机器人后台。直接点击页面左侧的「开发设置」。在这里，你可以得到 四项数据：机器人 QQ 号、ID、Token 和 Secret。记下这些数据，千万不要泄漏它们。

将 Koishi 对接机器人

回到 Koishi，点击左侧栏的「插件配置」，翻到插件列表的下方找到「adapter-qq」插件。分别填写需要的数据。注意此处数据的需求和顺序都和上文机器人后台中的不相同，请仔细对照后填写。

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

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

接下来，翻到下方的「消息事件权限」配置项，根据使用场景勾选对应权限：

• 群聊消息: 勾选 USER_MESSAGE
• 频道私信: 勾选 DIRECT_MESSAGES
• 公域频道: 勾选 PUBLIC_GUILD_MESSAGES
• 消息审核: 必须勾选 MESSAGE_AUDIT

权限说明：未申请的高级权限会导致连接失败，新手建议仅勾选上述基础权限

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

注意此处若填写错误将会直接导致机器人无法接入。填写时请务必仔细。 如果遇到问题，可以加入帖子最上方的用户交流群提问。企业用户可以通过企业绿色通道联系 Koishi 客服。

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

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

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

你可以选择在 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」并发送。你可以看到机器人正常工作。

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

后续操作

配置斜杠指令

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

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

向下翻动到「prefix」配置项，并按照图中填写。第一项为「/」，第二项不填。 这使得你的机器人在带斜杠和不带斜杠的情况下都能正确触发指令。

最后，点击右上角的「对勾」图标，重启 Koishi。

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

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

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

提测与上线

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

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

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

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

附录:参考资源

官方文档

• QQ机器人开发文档↗
• Koishi官方指南↗

社区支持

• Koishi用户交流群↗
• QQ开放平台开发者社区↗

遇到问题

如果你遇到问题，你应当首先收集与问题有关的全部信息。「Koishi 用户交流群群规」↗ 贴中给出了收集信息的方法：

提问时需要附带下列内容（通称「四项信息」）

1. 问题的详细说明：包括「我想要做什么」、「我已经做了什么」、「在什么操作的途中出了问题」

很多用户会直接发一张 Koishi 正常运行的图到群里，没有人能解答这样的问题

2. Koishi 窗口左下角的设备信息：点击左下角显示的 Koishi 版本，即可复制环境信息
3. 配置截图：与问题有关的配置截图 + 你修改过的配置截图

如果是某个插件未能正常工作，那么你需要截图完整的插件配置 如果你修改过任何配置（包括全局配置），都要截图你修改过的配置

4. 完整日志：截图 从问题发生前 Koishi 的启动开始，到此刻为止的全部的日志，推荐使用 长截图 功能；如果日志过长的话也可打包（压缩）上传完整日志到群文件，日志的获取可以查看下面的方法

Koishi 桌面收集日志的方法（二选一即可）：

方法一

1. 点按『「开始」菜单-所有应用-Windows工具』，在打开的文件夹中双击启动「事件查看器」
2. 在左侧选择「Windows日志-应用（Application）」
3. 在右侧选择「另存为所有事件」并保存为一个文件
4. 在群内发送这个文件

方法二

1. 点按通知区域的「Koishi」图标，然后点按「高级-打开数据目录」，然后进入「data」文件夹
2. 在打开的文件夹中找到「logs」文件夹，在其上单击右键或长按，选择「压缩为zip文件」
3. 在群内发送这个文件

Koishi 点亮黄灯

四项数据填写错误

Koishi 插件配置内，填写数据的需求和顺序都和上文机器人后台中的不相同，请仔细对照后填写。

intents 配置错误

如果插件的运行日志内出现如下字样（disallowed intents 字样）：

[W] adapter disallowed intents, will retry in 5s...

或如下字样（1006 字样）：

[W] adapter failed to connect to wss://api.sgroup.qq.com/websocket, code: 1006, will retry in 5s...

说明你的 intents 配置项配置错误。

翻到上方，重新根据教程配置 intents。注意你只能启用你具有权限的 intents。如果你不清楚你是否具有权限，那么就是没有，需要独立申请。

未配置源IP白名单

[W] qq GET /gateway response: { message: '接口访问源IP不在白名单', code: 11298, err_code: 40023002, trace_id: '39d4f3ec32a8add7c5ac5abdaaf8dc00' }
[W] adapter Error: Unauthorized, will retry in 5s...

这是因为在QQ开放平台的后续更新中
对用户要求 需要填入允许接入机器人的 源IP白名单

所以你需要在q.qq.com的对应的地方（应该是黄色标志的这里）

找到对应的配置项，填入你的对应IP，这样就可以接入QQ开放平台的机器人了

部分图片无法发送

QQ 并未提供发送本地图片的功能，但 Koishi 提供了此功能。 可以查看下方的帖子进行配置。

腾讯官方群聊机器人发图问题

①利用 公网部署 | Koishi，使你可以用手机流量访问你的 koishi （记得保护自己的 koishi 实例，安装 auth 插件防止其他人修改你的 koishi 配置） …

前往 腾讯官方群聊机器人发图问题

未来如果 QQ 提供了此功能，那么就不需要再进行配置。