QQ（OneBot11 / NapCat）

对接 NapCat / Lagrange / go-cqhttp 等 OneBot11 实现。支持正向 WS、反向 WS、HTTP 三种连接方式，callApi 通用转发——OneBot11 全部接口（含群管理）都能用。

适配器类型："onebot11"　源码：src/adapter/onebot11/ 协议：OneBot 11 标准，支持正向 WS、反向 WS、HTTP(webhook) 三种连接方式。

说明

特点

• 支持三种连接方式：反向 WS（推荐）、正向 WS、HTTP
• callApi 通用转发，OneBot11 全部接口都能用（群管理、点赞、撤回等）
• 兼容 NapCat、Lagrange、go-cqhttp 等所有 OneBot11 实现
• userId/groupId 为 QQ 号（数字），可直接用于发送/管理操作

原理

• 接收：NapCat 通过 WS 或 HTTP 上报 OneBot11 事件，适配器转为框架统一事件
• 发送：callApi(action, params) 原样转发给 NapCat（WS 经 echo 配对，HTTP 经 POST {apiUrl}/api/{action}）

前提

• 已部署 NapCat（或其他 OneBot11 实现）并登录 QQ 号
• NapCat 已配置对应连接方式（正向 WS / 反向 WS / HTTP 上报）

安装

适配器安装

van adapter install onebot11

依赖库

npm install ws

配置

方式一：反向 WS（NapCat 主动连本框架）——推荐

{
  "botId": "Van-None",
  "type": "onebot11",
  "mode": "ws_reverse",
  "port": 8080,
  "path": "/onebot/v1/ws",
  "token": ""
}

NapCat 配置"反向 WS"，地址填 ws://<本机IP>:8080/onebot/v1/ws。

方式二：正向 WS（本框架主动连 NapCat）

{
  "botId": "Van-None",
  "type": "onebot11",
  "mode": "ws_client",
  "url": "ws://127.0.0.1:3001",
  "token": ""
}

方式三：HTTP（NapCat HTTP 上报 + HTTP API）

{
  "botId": "Van-None",
  "type": "onebot11",
  "mode": "http",
  "port": 8080,
  "path": "/event",
  "apiUrl": "http://127.0.0.1:3000",
  "token": ""
}

配置说明

配置项	必填	说明
mode	可选	连接方式：ws_reverse（默认推荐）/ ws_client / http
port	ws_reverse/http	本框架监听端口
path	可选	监听路径，默认 "/"
url	ws_client	NapCat 正向 WS 地址
apiUrl	http	NapCat HTTP API 地址，默认 http://127.0.0.1:3000
token	可选	鉴权 token（NapCat 配置相同的 access_token）

接收事件

NapCat 推送的全部事件都会转成框架统一事件：

OneBot11 事件	框架事件	说明
message.group	group_message	群消息，groupId=群号、userId=QQ号
message.private	private_message	私聊消息
notice.*	notice	通知类事件（群成员变动、好友添加等）
request.*	request	请求类事件（加群、加好友等）

API 调用

OneBot11 适配器的 callApi 是通用转发：任意 OneBot11 action + params 原样发往 NapCat，NapCat 支持的全部接口都能用。

// 发送群消息
await bot.callApi("send_group_msg", { group_id: 123456789, message: "你好" })

// 发送私聊
await bot.callApi("send_private_msg", { user_id: 123456, message: "你好" })

// 自动判断
await bot.callApi("send_msg", { group_id: 123456789, message: "你好" })

// 群管理
await bot.callApi("set_group_ban", { group_id: 123456789, user_id: 123456, duration: 600 })
await bot.callApi("set_group_kick", { group_id: 123456789, user_id: 123456 })
await bot.callApi("delete_msg", { message_id: 12345 })
await bot.callApi("send_like", { user_id: 123456, times: 3 })
await bot.callApi("get_msg", { message_id: 12345 })

消息段 / CQ 码

message 支持字符串（含 CQ 码）或消息段数组：

// CQ 码字符串
"[CQ:image,file=xxx] 看图"
"[CQ:at,qq=123456] 你好"

// 消息段数组
[
  { type: "at", data: { qq: "123456" } },
  { type: "text", data: { text: " 你好" } },
  { type: "image", data: { file: "https://xxx/a.jpg" } }
]

Markdown：发送 [CQ:markdown,data={"content":"..."}] 字符串。

常见问题

• NapCat 连不上：确认 NapCat 端配置的连接方式与本框架 mode 对应（正向 WS ↔ ws_client，反向 WS ↔ ws_reverse）。
• 收不到消息：检查 NapCat 是否已登录、事件上报是否开启、端口是否被占用。
• 群管理接口报错：确认机器人 QQ 号在群里有管理员权限。

相关项目

• OneBot 11 规范：https://github.com/botuniverse/onebot-11
• NapCat：https://napneko.github.io/