前言

本教程是使用 Koishi 接入 QQ 和 QQ 频道的指南，摘自于koishi官方论坛，有问题也可以去官方论坛下面评论
koishi官方教程
作者使用Windows 10

准备

koishi
QQ开放平台账号

开始

开始之前……
需要注意：
从现在开始，需要严格按照本贴的指导操作。尤其注意不要做教程没有指导的事情。阅读本教程的用户有相当大的比例多选了 intents 或打开了 sandbox，最终导致机器人无法连接或无法收到消息。请注意严格阅读教程操作，不要多做或漏做步骤。

需要决定：
你需要先决定这两件事——

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

如果你是企业的话,请您转到官方教程
………………………………………….
2. 机器人的使用范围类型：是全量还是白名单？
如果创建全量机器人，那么你的机器人将可以被任何人添加到任何群。
如果创建白名单机器人，只有你能够指定机器人添加的群。

确定好再往下吧

下载、安装和使用 Koishi

先前往 Koishi 的官网下载并安装 Koishi。如果你是第一次接触 Koishi，我们推荐使用 Koishi 的 Windows 版本
koishi

…………….
此处需要你安装koishi
各种办法都可以
…………….

安装好在进行下一步吧

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

接着，点击左侧栏的「插件市场」，搜索并安装 echo 插件，测试能否正常安装新的插件

最后，点击左侧栏的「沙盒」，创建一个用户，并发送「帮助」测试 Koishi 本身的功能是否正常使用

结论:koishi本身没有问题可以正常使用

创建 QQ 机器人

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

如果准备以企业身份注册账号,请转到官方教程

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

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

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

将 Koishi 对接机器人

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

切记检查顺序,如果登陆不上先检查是否填写错误/填反

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

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

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

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

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

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

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

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

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

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

QQ群中测试

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

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

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

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

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

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

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

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

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

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

一些问题

配置斜杠指令

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

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

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

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

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

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

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

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

提测与上线

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

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

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

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

结论：你已提测机器人

koishi 没有亮绿灯而是黄灯

Koishi 点亮黄灯的原因可能有多种。继续翻动，排查每一种原因。

1.Koishi 插件配置内，填写数据的需求和顺序都和上文机器人后台中的不相同，请仔细对照后填写。
2.如果插件的运行日志内出现如下字样（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。如果你不清楚你是否具有权限，那么就是没有，需要独立申请。

部分图片无法发送

QQ 并未提供发送本地图片的功能，但 Koishi 提供了此功能。可以查看下方的帖子进行配置。
https://forum.koishi.xyz/t/topic/5960
未来如果 QQ 提供了此功能，那么就不需要再进行配置。

仍有问题

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

提问时需要附带下列内容（通称「四项信息」）
1.问题的详细说明：包括「我想要做什么」、「我已经做了什么」、「在什么操作的途中出了问题」
很多用户会直接发一张 Koishi 正常运行的图到群里，没有人能解答这样的问题

2.Koishi 窗口左下角的设备信息：点击左下角显示的 Koishi 版本，即可复制环境信息

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

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

可能需要

官方QQ群:391463133(一群)
官方QQ群:590104798(名字是非官方但是是官方)
koishi官方地址:koishi.chat
koishi论坛:https://forum.koishi.xyz

作者QQ群:698650116(不要被群名蒙蔽了双眼)
作者QQ机器人:三花喵