Discord 机器人邀请链接其实就是一个 OAuth2 授权网址:其中的 scope 参数决定请求的是哪种访问权限(机器人账号、斜杠命令,或两者兼有),而 permissions 数字则决定机器人账号加入后能做什么。服务器管理员必须批准整个请求,任何权限才会生效。理解这两个参数,正是构建安全邀请链接与盲目复制一个你无法完全了解的链接之间的区别。
邀请链接的结构
典型的机器人邀请链接如下所示:
https://discord.com/oauth2/authorize?client_id=123456789&permissions=268446800&scope=bot%20applications.commands
- client_id:应用程序的公开 ID,可以安全分享,每个该机器人的邀请链接中都包含它。
- scope:请求的访问类型,多个值之间用空格分隔(URL 编码为
%20)。 - permissions:一个数字,代表所请求的全部服务器权限之和。
- guild_id 和 disable_guild_select(可选):预先选中某个特定服务器,并将选择器锁定在该服务器上,适用于每个服务器专属的“把我添加到这里”按钮。
“bot”权限范围
这是真正将机器人添加为服务器成员的权限范围,即成员列表中旁边带有机器人标签的那个条目。如果没有这个权限范围,什么都不会加入,因为不存在可供授权的机器人账号。
“applications.commands”权限范围
此权限范围用于注册应用程序的斜杠命令、用户命令和消息命令,使其能够在该服务器中使用。从技术上讲,机器人只靠 bot 权限范围也可以加入,但当有人输入 / 时,它的任何 /commands 都不会出现,因为服务器从未授权命令注册。
为什么几乎总是两者都需要
只使用 bot 权限范围邀请的机器人,仍然可以发送消息、对其已发送消息上的按钮作出反应,并响应不需要斜杠命令的内容。但现代的 Discord 用户期望使用命令,而一个无法注册命令的机器人,即使运行完全正常,看起来也像是坏了。正因如此,Noxyr 生成的每一个邀请链接,以及几乎所有正规机器人的邀请链接,都会同时包含这两个权限范围。
解读权限数字
每一项 Discord 权限,例如发送消息、管理身份组、踢出成员,都是位域中的一个比特:即 2 的幂次标志。邀请链接中的数字,是所有同时请求的标志之和。如果链接请求的 permissions 为 8,那它只请求一样东西:管理员权限,即对服务器的完全、不受限制的访问。构建良好的邀请链接只会累加机器人代码实际使用的特定标志,例如用于创建工单频道的频道管理、用于验证身份组的身份组管理、用于反突袭响应的管理操作,而不是 Discord 提供的全部权限。
为什么管理员权限是危险信号,而不是硬性要求
大多数正规机器人并不需要它。请求该权限,要么是因为确实有少见的需求,需要同时触及几乎所有权限;要么——更常见的情况是——机器人是快速搭建的,随手把 permissions 设为 8,因为这是最容易想到的数字。它也是 Discord 在设置期间向服务器所有者展示的最吓人的一个界面,因此它常常是邀请被直接拒绝的原因,或者机器人之后被清理权限的人移除的原因。在点击“授权”之前,你可以使用 Discord 权限计算器解读任何邀请链接中的权限数字,准确查看它在请求什么。
以 Noxyr 的邀请链接为例
Noxyr 的邀请并不请求管理员权限,而是根据其功能实际使用的特定权限来构建:工单和验证所需的频道与身份组管理,反大规模破坏响应所需的消息和管理权限,除此之外别无其他。它始终同时包含 bot 和 applications.commands 两个权限范围,因此机器人一加入,其命令即可使用。
你可能会见到的其他 OAuth2 权限范围
除了 bot 和 applications.commands 之外,Discord 还定义了数十种 OAuth2 权限范围。其中大多数,例如 identify 或 guilds.join,属于“使用 Discord 登录”这类网页身份验证,而不属于机器人邀请,在标准邀请链接中根本不会出现。如果你看到的链接在 bot 之外还请求了某个陌生的权限范围,那么在授权之前值得先核实该权限范围实际授予了什么。因为除了提供账号关联的服务之外,机器人邀请合理地需要额外网页认证权限范围的情况是很少见的。
为你自己的自定义机器人构建邀请链接
在 Discord 开发者门户中创建应用程序后,OAuth2 选项卡中的 URL 生成器可以通过勾选框为你构建这个链接:在 scopes 下勾选 bot 和 applications.commands,勾选机器人所需的权限,然后复制生成的结果。这样就无需手动拼接网址和权限数字。
常见问题
disable_guild_select 有什么作用?它会将服务器选择器锁定在一个预先选定的服务器上,这样专为某个特定社区准备的邀请链接,就不会被意外用来把机器人添加到其他地方。
如果我的机器人只使用按钮,还需要 applications.commands 吗?对于它已发送消息上的按钮,严格来说不需要;但只要涉及任何斜杠命令,你就必须有它。
之后更改权限数字能追溯增加访问权限吗?不能。已经批准过邀请的服务器会保留当时授予的权限;更改链接只影响之后的邀请,已安装的机器人需要重新邀请并重新批准,才能获得更多权限。
只有 scope=bot 本身够用吗?对于让机器人加入而言是够用的,但如果没有 applications.commands 与之一起,它的斜杠命令不会出现。
为什么 Discord 对管理员权限显示如此大的警告?因为它请求的是对整个服务器的无限制访问,是机器人邀请可能请求的最危险的单一权限。
准备为自己的机器人设置邀请?请先阅读我们关于创建 Discord 应用程序的指南;如果你不想自己编写背后的代码,可以阅读自定义机器人文档。