Skip to main content

QQ 接入

PAI 通过 NapCat 实现 QQ 接入。NapCat 是一个兼容 OneBot v11 协议的 QQ 机器人框架,PAI 通过其 HTTP API 与 QQ 交互。

架构说明

NapCat 作为 OneBot 协议桥接层,将 QQ 消息转换为标准 OneBot 格式并通过 HTTP 回调推送给 PAI。

环境变量配置

string
required
NapCat 的 HTTP API 地址,例如 http://napcat:3000
string
OneBot HTTP API 的访问令牌,用于鉴权

Webhook 配置

端点: POST /webhook/qq NapCat 会将 QQ 消息通过 HTTP POST 推送到此端点。

Docker 部署

NapCat 作为独立服务在 Docker Compose 中运行,会自动配置回调地址指向 PAI 后端:
NapCat 容器启动时会自动配置 HTTP POST 回调地址为 http://backend:8000/webhook/qq,无需手动设置。
1

启动 NapCat 服务

通过 Docker Compose 启动 NapCat 容器
2

登录 QQ 账号

按照 NapCat 的登录流程完成 QQ 账号认证
3

验证联通

向 QQ Bot 发送私聊消息,确认 PAI 能正确接收和回复

消息格式

QQ 消息使用 OneBot 的 CQ 消息数组格式(message segment array):
PAI 会解析 CQ 消息数组,提取文本内容并转换为 UnifiedMessage

功能支持与限制

当前仅支持私聊消息,群聊消息不会被处理。

文本消息

支持接收和发送文本消息,完整的 AI 对话能力。

图片消息

当前 QQ 平台暂不支持图片消息的接收和发送。

消息处理流程