Skip to main content

​
QQ 接入

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

​
架构说明

QQ 用户 ←→ QQ 服务器 ←→ NapCat (OneBot 协议) ←→ PAI 后端
                           (port 3000)
NapCat 作为 OneBot 协议桥接层，将 QQ 消息转换为标准 OneBot 格式并通过 HTTP 回调推送给 PAI。

​
环境变量配置

​
ONEBOT_BASE_URL
string
required
NapCat 的 HTTP API 地址，例如 http://napcat:3000
​
ONEBOT_ACCESS_TOKEN
string
OneBot HTTP API 的访问令牌，用于鉴权
ONEBOT_BASE_URL=http://napcat:3000
ONEBOT_ACCESS_TOKEN=your-access-token

​
Webhook 配置

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

​
Docker 部署

NapCat 作为独立服务在 Docker Compose 中运行，会自动配置回调地址指向 PAI 后端： 
napcat:
  image: napcat/napcat:latest
  ports:
    - "3000:3000"
  volumes:
    - napcat_config:/config
  environment:
    - NAPCAT_HTTP_POST_URL=http://backend:8000/webhook/qq
  restart: unless-stopped
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）： 
[
  {
    "type": "text",
    "data": {
      "text": "你好，帮我查一下明天的天气"
    }
  }
]
PAI 会解析 CQ 消息数组，提取文本内容并转换为 UnifiedMessage。

​
功能支持与限制

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

​
文本消息

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

​
图片消息

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

​
消息处理流程

QQ 用户发送私聊消息
    │
    ▼
QQ 服务器 → NapCat (OneBot)
    │
    ▼
NapCat 推送 CQ 消息数组到 POST /webhook/qq
    │
    ▼
解析 CQ 消息数组，提取文本内容
    │
    ▼
转换为 UnifiedMessage(platform_id="qq", content=...)
    │
    ▼
AI 核心管线处理
    │
    ▼
UnifiedSender → NapCat send_private_msg API → QQ 服务器 → 用户收到回复