onebot.js

OneBot 11 正向 WebSocket 客户端 SDK（TypeScript、仅 ESM）。

以 OneBot 11 标准协议为主，同时附带 NapCat 扩展 API（与标准协议不冲突，故直接收录）。注意：扩展 API 仅在 NapCat 上保证可用，其他实现调用时可能报错，兼容边界后续会改进。

本项目 fork 自 node-napcat-ts（MIT）， 感谢原作者 @huankong233 及各位贡献者。

安装

pnpm add onebot.js

要求 Node.js >= 22。本包仅支持 ESM（import）；CJS 环境请使用 await import('onebot.js')。

快速开始

connect() 建立正向连接：连接成功后才返回 OneBotClient 对象； 按 reconnection 的预算自动重试，全部失败会直接抛出异常，由调用者处理。

import { connect, Structs } from 'onebot.js'

const bot = await connect({
  baseUrl: 'ws://127.0.0.1:3001',
  accessToken: 'your token', // 以 query 参数追加（OneBot 11 正向 WS 约定），可选
  // reconnection: { enable: true, attempts: 10, delay: 5000 }, // 自动重连，可选
  // logger: console, // 日志出口，可选；省略时默认使用 console（自定义 logger 需带 info/warn/debug）
})

// 收消息（事件名支持 message / notice / request / meta_event 及分层子事件）
bot.on('message', (context) => {
  console.log(context.sender.nickname, context.raw_message)
})

// 发消息
bot.on('message', async (context) => {
  if (context.raw_message === 'echo') {
    await bot.send_msg({ ...context, message: [Structs.text('pong')] })
  }
})

也可以不经过 connect()，直接实例化并自行管理生命周期：

import { OneBotClient } from 'onebot.js'

const bot = new OneBotClient({ baseUrl: 'ws://127.0.0.1:3001' })
await bot.connect()   // 等待连接建立
await bot.disconnect() // 主动断开

更多用法见 docs：如何使用 · 绑定事件 · 调用接口 · 结构体构造器。

文档

• NapCatQQ 文档 — 实现端行为参考
• go-cqhttp 文档
• OneBot 11 文档

License

MIT