QQ Bot WebSocket 网关架构详解 — 四层连接流程与配置手册

架构

config.ts (QQConfig)
  ↓ appId + appSecret
bot.ts (QQBot)
  ↓ WebSocket 网关
channel.ts (QQChannel)
  ↓ 消息收发
use-qq-channel.ts (React Hook)
  ↓ TUI 集成
App.tsx

连接流程（bot.ts）

1. 获取 Token → POST https://bots.qq.com/app/getAppAccessToken

{ appId, clientSecret } → { access_token, expires_in }

2. 获取网关地址 → GET {baseUrl}/gateway

Authorization: QQBot {token} → { url: "wss://..." }

正式环境 api.sgroup.qq.com，沙箱环境 sandbox.api.sgroup.qq.com

3. WebSocket 连接 → new WebSocket(gatewayUrl)

headers: { Authorization: "QQBot {token}", "X-Union-Appid": appid }

4. 收到 op=10 (Hello) → 回复 IDENTIFY (op=2)：

{ token: "QQBot {token}", intents: 1<<25, shard: [0,1] }

5. 收到 READY 事件 → bot 上线，触发 online 事件

6. 私聊消息 → C2C_MESSAGE_CREATE 事件 → message.private

配置（config.ts）

{
  "qq": {
    "appId": "你的AppId",
    "appSecret": "你的AppSecret",
    "sandbox": true,
    "ownerOpenId": "你的OpenId（可选）",
    "allowlist": ["其他OpenId（可选）"]
  }
}

sandbox: true → 沙箱环境（开发用）
ownerOpenId → 仅此用户可交互（安全模式）
allowlist → 白名单用户
都留空 → 开放模式（第一个发消息的用户自动绑定）

消息收发

接收（channel.ts :: handlePrivateMessage）：

• 过滤重复消息
• 校验访问权限（owner/allowlist/runtime/open）
• 转为 [QQ] 用户消息 提交给 AI

发送（bot.ts :: sendPrivateMessage）：

• POST {baseUrl}/v2/users/{openid}/messages
• 自动分片（1500 字节/片）
• 支持 msg_id 回复链和 msg_seq 排序

启动命令

在 Reasonix TUI 中：/qq start 或 /qq connect

需要我先帮你配置 TUI 中的 QQ 连接入口吗？

---

— END —