2024 年最新使用 Node 搭建QQ开放平台官方 QQ 频道机器人详细教程（更新中）

注册 QQ 开放平台账号

QQ 开放平台是腾讯应用综合开放类平台，包含 QQ 机器人、QQ 小程序、QQ 小游戏 等集成化管理，也就是说你注册了QQ 开放平台，你开发 QQ 机器人还是 QQ 小程序都是在这个平台进行部署上线和管理。

如何注册 QQ 开放平台账号？点击首页右上角【立即注册】

注意主体的选择，当然无论是企业还是个人，都是可以开发 QQ 小程序 或者 QQ 机器人 的，但是如果您是个人主体的话，那么你的权限将有所局限，因为部分服务权限是需要企业主体的。

企业主体入驻开发者默认支持频道、群场景开发能力；个人主体入驻开发者默认仅支持频道场景开发能力。除默认开通的能力外，后续其他接口能力申请上，企业开发者与个人开发者也存在差异。

温馨提示：姓名和身份证号码务必与手机号码对应运营商实名登记的信息一致，否则会提示错误。

创建 QQ 机器人

注册完成后登陆开放平台！在机器人分栏点击【创建机器人】

填写 QQ 机器人资料信息（名称、头像、介绍）

QQ 机器人管理端后台

QQ频道机器人是一种对QQ频道进行功能扩展的程序，通过开放的接口，让开发者能够实现开发出交互形式丰富的机器人，以辅助实现频道/社群内的管理、消息互动，满足频道主或群主运营者多样化、个性化的运营需求，从而提高运营效率，同时为用户带来丰富的服务和便捷的体验。

资料提交成功后，即会生成 appid，点击对应的应用即可跳转管理端。

机器人类型 和 测试频道 / 群 配置

机器人类型 包含 私域机器人或者 公域机器人。当然公域机器人对于服务器的要求过高，我们这边也可以选择私域机器人进行开发。特别注意在选择沙箱测试频道的时候，你必须提前创建个沙箱测试频道，必须＜20人的频道。但是选择沙箱测试 QQ 群则需要您是企业资质。

沙箱频道仅可设置当前用户为频道主/管理员的频道、沙箱群仅可设置当前用户为群主/群管理员的群，且沙箱频道成员、沙箱群成员不可大于20人。

在沙箱配置页面不同类型开发者支持开发不同场景机器人功能

建议开发者根据实际的需要，选择在不同场景开发机器人，完成对应场景的沙箱环境配置。配置沙箱后，开发者可在「功能配置」、「使用范围与人员」页面解锁相应场景的配置能力。

认证身份	QQ频道	QQ群	消息列表单聊
企业开发者	✅	✅	申请后可开发
个人开发者	✅	暂不开放	暂不开放

配置沙箱 QQ 群 / 频道，需要先在QQ客户端创建符合沙箱要求的QQ群/QQ频道。在频道场景，机器人仍然保留「公域」/「私域」机器人的区分，设置为公域机器人保存确认后不可切换为私域机器人，但在「使用范围与人员」可设置公域机器人的允许添加范围：“全部用户可添加”/“仅白名单用户可添加”。配置沙箱频道/群后，机器人会出现在沙箱频道/沙箱群的机器人列表当中。

搭建 qq-guild-bot 环境

国内安装 qq-guild-bot 使用腾讯源

npm i qq-guild-bot --registry=https://mirrors.tencent.com/npm/

配置 .env 文件：机器人信息

appId=申请机器人时获取到的机器人 BotAppID
token=申请机器人时获取到的机器人 BotToken

启动案例

const { createOpenAPI, createWebsocket } = require('qq-guild-bot');

const testConfig = {
	appID: process.env.appId,
	token: process.env.token,
	intents: ['PUBLIC_GUILD_MESSAGES'],
	sandbox: false,
};

const client = createOpenAPI(testConfig);

const ws = createWebsocket(testConfig);

配置属性说明

属性	说明	案例值
appID	申请机器人时获取到的机器人 BotAppID	process.env.appId
token	申请机器人时获取到的机器人 BotToken	process.env.token
intents	事件订阅，用于开启可接收的消息类型	[‘PUBLIC_GUILD_MESSAGES’]
sandbox	沙箱支持，可选，默认 false（v2.7.0+及以后版本）	false

请注意 process.env.appId 和 process.env.token是环境变量中存储的实际值，它们通常用于保护敏感信息，例如 API 密钥或令牌。在真实的应用程序中，您不会直接在代码中硬编码这些值，而是使用环境变量或配置文件来安全地存储和访问它们。

intents 可选值举例：

['GUILDS', 'GUILD_MEMBERS', 'GUILD_MESSAGES','GUILD_MESSAGE_REACTIONS','DIRECT_MESSAGE', 'INTERACTION','MESSAGE_AUDIT','FORUMS_EVENT','AUDIO_ACTION', 'PUBLIC_GUILD_MESSAGES']

频道 API 官方文档

QQ机器人文档：https://bot.q.qq.com/wiki/develop/api-v2/

频道消息事件

{
	eventType: 'AT_MESSAGE_CREATE',
	eventId: 'AT_MESSAGE_CREATE:9cf66025-fd89-4474-8cff-5b653f13b793',
	msg: {
		author: {
			avatar: 'https://qqchannel-profile-1251316161.file.myqcloud.com/1690525084d31f5da18614da93?t=1690525084',
			bot: false,
			id: '3099335931735309862',
			username: '唤醒手腕'
		},
		channel_id: '633953187',
		content: '<@!4609307794105190966> 测试',
		guild_id: '11682521373910822180',
		id: '08a4daf3e6afe9a990a20110a3b7a5ae02381a48e5add3b006',
		member: {
			seq_in_channel: '26',
			timestamp: '2024-04-09T13:49:25+08:00'
		}
	}
}

回复事件

{
	eventType: 'READY',
	msg: {
		version: 1,
		session_id: 'fb73286a-fa79-4b52-a68b-193e3380e022',
		user: {
			id: '4609307794105190966',
			username: '边缘骇客机器人-测试中',
			bot: true,
			status: 1
		},
		shard: [0, 1]
	}
	member: {
		joined_at: '2023-11-09T22:46:01+08:00',
		nick: '唤醒手腕',
		roles: [Array]
	},
	mentions: [
		[Object]
	],
	seq: 24,
	seq_in_channel: '24',
	timestamp: '2024-04-09T13:45:49+08:00'
}

待更新······