QQ/QQ 频道 登录指南

本贴是使用 Koishi 接入 QQ 和 QQ 频道的指南。


■ 企业绿色通道 ■

如果您是企业用户,除了参考下面的教程创建 QQ 机器人以外,还可以添加 Koishi 客服 QQ:2953529126,获得一对一专属支持。


温馨提醒

本贴的阅读和操作时间总共约为 10 分钟。为了保证阅读体验,首次阅读时请点击我的头像,然后点击右侧的「筛选帖子」。

image

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

7 个赞

开始之前……

需要注意

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


需要决定

你需要先决定这两件事

  1. 你的身份:是 个人 还是 企业
  2. 你的机器人类型:是 私域 还是 公域

企业需要你自己有个体户身份,或有一个正在运营的公司。选择企业身份后,你可以获得更多的机器人权限。

  • 如果运营公域机器人,那么你的机器人将比私域的权限更少,但将可以被任何人添加到任何群(也可以禁止添加)。
  • 如果创建私域机器人,只有你能够指定机器人添加的群。
3 个赞
步骤 ①

下载、安装和使用 Koishi

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

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

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

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

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

4 个赞
步骤 ②

创建 QQ 机器人

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

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

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

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

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

3 个赞
步骤 ③

将 Koishi 对接机器人

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

之后,根据上文创建机器人时的选择,填写机器人是公域(public)还是私域(private)。 公私域类型可以在开放平台的「基础信息 - 资料」中查看。

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

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

  • 如果你已获得 QQ 群机器人资格,并准备在 QQ 群中使用,勾选 USER_MESSAGE
  • 如果你准备在 QQ 频道的 频道私信 列表中使用,勾选 DIRECT_MESSAGES
  • 如果你准备在 QQ 频道中使用,且你的机器人是私域机器人,勾选 GUILD_MESSAGES
  • 如果你准备在 QQ 频道中使用,且你的机器人是公域机器人,勾选 PUBLIC_GUILD_MESSAGES
  • 如果你有发送主动消息的需求,勾选 MESSAGE_AUDIT。如果你不知道自己有没有这个需求,那就是有,请勾选。

目前,

  • 所有用户默认带有频道权限,但只有选定的公域 私域权限;
  • 企业用户默认带有群权限;
  • 参加了 5295 贴 开发者大赛的个人用户拥有群权限;
  • 其他个人用户需要等待后续群权限的开放。

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

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

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

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

3 个赞
步骤 ④

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

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

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

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

2 个赞

下面的内容有「疑难解答」和「后续」两部分。如果你遇到问题或还想继续进行后续步骤,那么可以继续往下阅读。

2 个赞
后续 ①

配置斜杠指令

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

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

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

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

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

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

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

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

3 个赞
后续 ②

提测与上线

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

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

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

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

结论:你已提测机器人。

2 个赞

遇到问题

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


收集信息后,翻阅下方的讨论,查找是否有与你的问题相同的问题,并按照解决方法操作。如果没有找到相同的问题,那么你现在可以带上全部的信息回帖。

2 个赞
疑难解答 ①

Koishi 点亮黄灯

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

2 个赞
疑难解答 ②

Koishi 点亮黄灯(四项数据填写错误)

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

2 个赞
疑难解答 ③

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。如果你不清楚你是否具有权限,那么就是没有,需要独立申请。

如果遇到问题,可以加入帖子最上方的用户交流群提问。企业用户可以通过企业绿色通道联系 Koishi 客服。

1 个赞
疑难解答 ④

部分图片无法发送

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

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

1 个赞
疑难解答 ⑤

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

1 个赞
疑难解答 ⑥

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

1 个赞
疑难解答 ⑦

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

2 个赞
疑难解答 ⑧

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

1 个赞
疑难解答 ⑨

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

2 个赞
疑难解答 ⑩

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

1 个赞