QQ 官方机器人

QQ 开放平台官方机器人。支持 websockets（官方加密网关）/ ws / webhook 三种接收方式，发送统一走 OpenAPI REST。接收最全（文本 / @ / 图片 / 视频 / 语音+ASR / 文件 / 引用 / ARK 卡片 / 表情），发送支持富媒体与 markdown + 按钮（keyboard）。

适配器类型："qq"　源码：src/adapter/qq/ 协议：QQ 开放平台官方机器人（api-v2，网关 + REST 发送），与 onebot11 无关。

说明

特点

• 支持三种接收方式：websockets（官方加密网关 wss://）、ws（明文网关）、webhook（HTTP 回调）
• 发送统一走 OpenAPI REST，支持文本、图片、视频、语音、文件、Markdown、按钮
• 接收事件最全：群@、单聊、群消息、频道消息、好友/群关系事件、按钮交互、消息审核
• 两种凭据模式：AppSecret（自动换取 access_token）或 BotToken（直接使用）

原理

• 接收：WebSocket 网关订阅事件（intents 按位或），或 HTTP 回调接收推送
• 发送：POST https://api.bot.qq.com/v2/...，请求头 Authorization: QQBot {access_token}
• 富媒体：先调 /files 上传获取 file_info，再以 msg_type:7 + media.file_info 发送

前提

• QQ 开放平台注册并创建机器人，获取 AppID 与 AppSecret（或 BotToken）
• 机器人已加入目标群（群设置 → 群机器人 → 添加）
• websockets/ws 模式国内可直连，无需公网回调；webhook 模式需要公网可访问的回调 URL

安装

适配器安装

van adapter install qq

依赖库

npm install ws

配置

方式一：websockets（官方加密网关）——默认

{
  "botId": "QQ-Official",
  "type": "qq",
  "mode": "websockets",
  "appId": "你的Appid",
  "appSecret": "你的AppSecret",
  "intents": 33554432,
  "gateway": "",
  "reconnectDelay": 5000
}

方式二：ws（明文 WebSocket 网关）

{
  "botId": "QQ-Official",
  "type": "qq",
  "mode": "ws",
  "appId": "你的Appid",
  "appSecret": "你的AppSecret",
  "gateway": "ws://127.0.0.1:8080",
  "intents": 33554432
}

方式三：webhook（HTTP 回调）

{
  "botId": "QQ-Official",
  "type": "qq",
  "mode": "webhook",
  "appId": "你的Appid",
  "appSecret": "你的AppSecret",
  "port": 8080,
  "path": "/",
  "intents": 33554432
}

配置说明

配置项	必填	说明
mode	可选	接收方式：websockets（默认）/ ws / webhook
appId	✅	QQ 开放平台 AppID
appSecret	二选一	AppSecret，自动换取 7200 秒有效的 access_token
botToken	二选一	群机器人令牌，access_token = AppID.BotToken，无需换取
intents	可选	事件订阅位掩码，默认 33554432（群聊+单聊）
gateway	可选	网关地址，默认自动获取；ws 模式必填明文网关地址
port	webhook 模式	HTTP 回调监听端口，默认 8080
path	webhook 模式	回调路径，默认 "/"
reconnectDelay	可选	断线重连延迟毫秒，默认 5000

intents 订阅

默认订阅 GROUP_AND_C2C_EVENT | GUILD_MESSAGES | PUBLIC_GUILD_MESSAGES。如需更多事件，按位或后填入：

Intent	值	覆盖事件
GUILDS	1	频道相关
GUILD_MEMBERS	2	频道成员变动
GUILD_MESSAGES	512	频道消息
GUILD_MESSAGE_REACTIONS	1024	频道消息表态
DIRECT_MESSAGE	4096	频道私信
GROUP_AND_C2C_EVENT	33554432	群@+单聊+好友/群关系事件（默认）
INTERACTION	67108864	交互事件（按钮）
MESSAGE_AUDIT	134217728	消息审核
FORUMS_EVENT	268435456	论坛事件（仅私域）
AUDIO_ACTION	536870912	音频动作
PUBLIC_GUILD_MESSAGES	1073741824	公域频道消息

接收事件

QQ 事件 t	框架事件	说明
GROUP_AT_MESSAGE_CREATE	group_message	群里 @ 机器人
C2C_MESSAGE_CREATE	private_message	用户单聊机器人
GROUP_MESSAGE_CREATE	group_message	群消息（需订阅）
MESSAGE_CREATE / AT_MESSAGE_CREATE	group_message	频道消息
GROUP_ADD_ROBOT / GROUP_DEL_ROBOT / FRIEND_ADD 等	notice	好友/群/单聊关系事件
INTERACTION_CREATE	notice	按钮点击回调

事件对象字段：

{
  botId: "QQ-Official",
  selfId: "102123456",
  userId: "USER_OPEN_xxx",      // 用户 openid
  groupId: "GROUP_OPEN_xxx",    // 群 openid
  message: [{ type: "text", data: { text: "你好" } }],
  postType: "group_message" | "private_message" | "notice",
  raw: { ...原始事件, sender: {user_id, member_openid, user_openid}, message_id, time, platform: "qq-official" }
}

消息段

类型	消息段	数据来源
文本	text	content（已去 @机器人 前缀）
图片	image	attachments[]（content_type=image/*）
视频	video	attachments[]（content_type=video/*）
语音	record	attachments[]（含 asr 语音转文字）
文件	file	attachments[]（content_type=file）
引用消息	reply	message_type=103
@某人	at	mentions[]
表情	face	content 内 <emoji:id/>
ARK 卡片	json	message_type=3 + ark_data

QQ 使用 openid（不是 QQ 号），userId/groupId 都存 openid。

API 调用

插件统一通过 bot.callApi(action, params) 调用。

发送消息

action	说明	关键参数
send_group_msg	发送群消息	group_id, message
send_private_msg	发送单聊	user_id, message
send_msg	自动判断群/私聊	group_id 或 user_id, message

await bot.callApi("send_msg", { group_id: "GROUP_OPEN_xxx", message: "大家好" })

消息段

message 支持字符串或段数组：

// 纯文本
{ type: "text", data: { text: "文本" } }

// Markdown（需开通权限）
{ type: "markdown", data: { content: "# 标题\n**加粗**" } }

// Markdown + 按钮
[
  { type: "markdown", data: { content: "# 标题" } },
  { type: "button", data: { text: "点赞", callback: "like" } },
  { type: "button", data: { text: "官网", url: "https://qq.com", row: 1 } }
]

// 富媒体（图片/视频/语音/文件）
{ type: "image",  data: { url: "https://example.com/a.jpg" } }
{ type: "video",  data: { url: "https://example.com/v.mp4" } }
{ type: "record", data: { url: "https://example.com/v.silk" } }
{ type: "file",   data: { url: "https://example.com/a.pdf" } }
{ type: "image",  data: { file: "base64://iVBORw0KGgo..." } }

撤回消息

action	说明	关键参数
delete_msg / recall_msg	自动判断群/私聊撤回	message_id, group_id 或 user_id

只能撤回机器人自己发的、且发送未超过 2 分钟的消息。

查询消息

action	说明	关键参数
get_msg	获取单条消息	message_id, group_id 或 user_id
get_group_msg_list	群消息列表	group_id

富媒体文件

action	说明	关键参数
upload_group_file	上传群文件	group_id, file_type(1图/3视频/4语音/5文件), url 或 file_data
upload_private_file	上传单聊文件	user_id, file_type, url 或 file_data

表情表态

action	说明	关键参数
set_msg_emoji_like	消息表情表态	message_id, group_id 或 user_id, emoji_type
delete_msg_emoji_like	取消表态	message_id, group_id 或 user_id

群管理

action	说明	关键参数
get_group_member_list	群成员列表	group_id
get_group_member_info	群成员信息	group_id, member_openid / user_id
set_group_ban	禁言成员	group_id, member_openid, duration（秒）
unset_group_ban	解除禁言	group_id, member_openid
set_group_kick	移出群	group_id, member_openid
set_group_nickname	设置群昵称	group_id, member_openid, nickname

群管理接口认 member_openid（事件 raw.sender.member_openid），不是 user_openid。

C2C / 好友

action	说明	关键参数
set_friend_add	加好友	user_id
delete_friend	删好友	user_id
set_user_block	拉黑用户	user_id
unset_user_block	解除拉黑	user_id

按钮回调回应

用户点击按钮后推送 INTERACTION_CREATE 事件，需调用本接口回应：

if (event.raw.notice_type === "INTERACTION_CREATE") {
  await bot.callApi("reply_interaction", {
    interaction_id: event.raw.interaction_id,
    code: 0
  })
}

其他

action	说明
get_self_info / get_me	获取机器人自身信息
get_audit_result	消息审核结果（需订阅 MESSAGE_AUDIT）

常见问题

• appId/botToken 从哪来：QQ 开放平台 → 创建机器人 → 开发设置 → 查看 AppID 与 BotToken。
• 机器人怎么进群：群设置 → 群机器人 → 添加你的机器人（需群主/管理员）。个人开发者可加进 ≤20 人的测试群。
• 群 openid 哪来：机器人收到群消息后，事件里的 groupId 就是群 openid。
• 机器人主动私聊用户有限制：QQ 限制机器人主动发消息次数（每月 3 条），被 @ 或用户先私聊后被动回复无限。
• 收不到群里所有消息：只订阅 GROUP_AND_C2C_EVENT 时，群消息默认只在 @ 机器人时推送。需在开放平台控制台开启"接收所有消息"。
• 机器人自己发的消息收不到：QQ 官方平台本身不推送机器人自己发出的消息。

相关项目

• QQ 开放平台官方文档：https://bot.q.qq.com/wiki/
• 事件订阅 intents：https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html