QQ 群

准备一个 QQ 群

准备一个自己为群主，人数在 20 人以内的 QQ 群。

创建机器人

腾讯官方已逐步开放所有机器人的群权限。如果你此前已经为 QQ 频道创建过机器人，可以直接将这个机器人用于群。

如果你此前没有机器人，需要先申请一个。

打开 QQ 开放平台，点击【立即注册】，帐号类型选择【个人】，随后按表单提示一步步进行即可。

注册完成后，点击【创建机器人】按钮。随后跟随步骤操作。名称、头像和介绍可以按自己的喜好填写。

创建完成后，进入机器人后台页面，选择【沙箱配置】菜单。在【QQ 群 ID】选项中选择你要使用的 QQ 群。

2025/06/12 更新：目前似乎有新注册的机器人没有 QQ 群功能的情况，暂不清楚具体原因。

加入机器人

在手机 QQ 中，打开 QQ 群的设置页面，找到【群机器人】菜单。点击菜单打开机器人列表，找到你的机器人（通常在列表底部），点击添加即可。

登录机器人

完成了创建机器人并加入群的步骤后，接下来就可以下载机器人软件，并登录机器人进行使用了。

登录所需的参数和 QQ 频道的步骤相同。

QQ 群的能力限制

QQ 群的能力限制

由于官方接口能力不足，在 QQ 群中使用机器人会有许多限制之处。请大家在使用前了解以下限制，以提前避免不必要的疑问和困扰。

IP 白名单限制

目前新注册的机器人在使用正式环境登录时，必须在 QQ 开放平台配置 IP 白名单，否则无法连接到机器人；命令行会提示“接口访问源IP不在白名单”的错误。

IP 白名单配置方法：

程序启动后会在命令行中打印出当前公网 IP 地址。可将该地址配置到 QQ 开放平台【开发设置】→【IP白名单】 中，再进行连接操作。

有关 IP 白名单的说明

如果你使用个人电脑（非服务器）运行机器人，电脑的 IP 地址可能会因为重启、重新联网等情况发生变更。如果遇到“接口访问源IP不在白名单”的错误，你可能需要重新设置 IP 白名单。

如果你在这方面遇到问题，或不想频繁设置 IP 白名单，可选择使用【沙箱环境】。

不支持获取机器人所在群的信息

影响：首次登录机器人时，在频道选择页面，需要用户在群里手动 @ 一次机器人，群的信息才会显示在列表中。且只能获取群的 OpenID，无法获取群名称和头像。

只能监听到用户 @ 机器人的消息

影响：用户必须 @ 机器人才能收到指令。log 记录无法记录没有 @ 机器人的普通消息

机器人无法获取用户的昵称

影响：机器人回复的消息和后台的用户选择器中，用户的昵称默认显示为 OpenID

为了解决这个问题，我们提供了三种方式：

1. 可以在后台为每个用户单独设置昵称
2. 用户可以在群内使用 nick 指令设置昵称
3. 当用户使用 nn 指令关联人物卡时，若用户没有昵称，会将人物卡名称作为用户的昵称。

机器人无法获取回复消息和表情表态

影响：无法使用对抗检定和表情表态掷骰

机器人无法获取消息中 @ 其他人的内容

影响：无法使用常规的代骰

替代方案：在 QQ 群中不要直接 @ 他人（蓝字的 @），可以改用纯文本的 @。可以 @ 人物卡名或用户的昵称

机器人回复的消息会开头强制 @ 发送者，且不支持其余的 @

影响：自定义回复和自定义文案中的 {{at用户}} 会被吞。建议使用 {{用户名}} 或 {{人物卡名}} 替代。

机器人私聊需配置白名单

影响：暗骰和私聊机器人需要额外配置才能生效，否则机器人无法向用户发送私信消息。

配置方式：

首先登录 QQ 机器人后台，在【沙箱配置】-> 【在消息列表配置】中添加可以和机器人私聊的用户。

其次，用户在 QQ 中打开机器人的资料卡，点击【添加使用】按钮，把机器人添加到自己的联系人列表。（只有在机器人后台添加了这个用户，才会出现这个按钮）。只有与机器人成为好友，机器人才可以向用户发消息。若未完成此步骤，机器人发消息会在命令行出现错误提示。

随后，在机器人资料卡中点击【发消息】按钮，就可以向机器人发消息了，发送骰子指令也会得到机器人的回复。

机器人私聊主动消息限制，且不支持使用群消息 ID 发送被动消息

2025/04/21 更新：官方干掉了机器人发送主动消息功能，这会影响暗骰消息，在发送给玩家私信时，命令行会提示“主动消息失败, 无权限”报错。

若遇到这种错误，可尝试在私聊中主动向机器人发一条消息（可将主动消息转化为被动消息），即可在 5min 内再次接收机器人的私信。