Onebots
基于icqq的多例oneBot管理应用
Last verified:
What is Onebots?
Onebots 是一个多平台多协议机器人应用框架，基于 NodeJS 提供 M Platform => N Protocol 的解决方案。它提供完整的服务端和客户端解决方案，连接各大平台与主流机器人框架，统一各大平台的差异，输出标准的 OneBot、Satori、Milky 协议。
核心功能包括：内置 15+ 主流平台适配器（QQ、ICQQ、微信、钉钉、飞书、企业微信、Telegram、Slack、Discord、Kook、Microsoft Teams、Line、Email、WhatsApp、Zulip 等），一个账号可同时提供 OneBot V11/V12、Satori、Milky 等多种协议接口。imhelper 客户端 SDK 提供统一的客户端接口，抹平不同协议的差异，支持 WebSocket、Webhook、SSE 多种接收方式。
Onebots 适合机器人开发者、需要跨平台机器人解决方案的团队、以及使用 Koishi、NoneBot、Yunzai 等机器人应用框架的开发者。服务端场景适用于当框架不直接支持某平台时作为桥梁；客户端场景适用于需要开发跨协议机器人应用时提供统一接口。
项目基于 TypeScript 开发，提供完整的类型定义和代码提示，适配器和协议均支持动态加载，按需安装使用，代码结构清晰，服务端和客户端分离，易于扩展和维护。
Onebots pricing
Pricing model: Freemium
onebots 是开源免费项目，通过 npm install -g onebots 或 pnpm add -g onebots 可全局安装，也可通过 npm install onebots 进行项目安装。没有付费计划或商业版本，所有功能免费使用。用户只需自行准备平台账号（如 QQ 机器人、微信公众号等）并承担服务器部署成本。适配器和协议均按需单独安装，如 @onebots/adapter-wechat、@onebots/protocol-onebot-v11 等。
Onebots pros
- 支持 15+ 主流平台适配器包括 QQ、微信、Discord、Telegram 等
- 一个账号可同时提供 OneBot V11/V12、Satori、Milky 多种协议
- 内置服务端和客户端 SDK 完整解决方案
- 基于 TypeScript 开发，提供完整类型定义和代码提示
- 适配器和协议支持动态加载，按需安装
- 简单配置即可启动服务端
- 支持 HTTP API 和 WebSocket 多种通信方式
- 清晰的代码结构，服务端和客户端分离
- 易于扩展和维护
- 支持 Koishi、NoneBot、Yunzai 等主流机器人框架
- imhelper 客户端 SDK 抹平协议差异
- 支持 WebSocket、Webhook、SSE 多种消息接收方式
- 开源免费，可通过 npm/pnpm 全局或项目安装
- 支持 Windows、macOS、Linux 全平台
- 可轻松扩展自定义适配器和协议
Onebots cons
- 需要 Node.js >= 22 较高版本要求
- 需要为每个平台单独注册账号并配置凭证
- 部分平台适配器需要额外安装依赖包
- 配置文件对新手可能较复杂
- 需要自行部署服务器
- 微信等部分平台需要官方审核
- 某些平台功能可能受限于平台 API 限制
- 需要熟悉 OneBot/Satori 等协议概念
Frequently asked questions about Onebots
什么是 onebots？
onebots 是一个多平台多协议机器人应用框架，基于 NodeJS 提供 M Platform => N Protocol 的解决方案。它提供完整的服务端和客户端解决方案，连接各大平台（QQ、微信、钉钉、飞书、企业微信、Telegram、Slack、Discord 等）与主流机器人框架（Koishi、NoneBot、Yunzai 等），统一各大平台的差异，输出标准的 OneBot V11/V12、Satori、Milky 协议接口。
onebots 支持哪些平台？
onebots 内置 15+ 主流平台适配器，包括 QQ 官方机器人、ICQQ、微信（公众号）、微信 ClawBot (iLink)、Kook、Discord、Telegram、飞书、钉钉、Slack、企业微信、Microsoft Teams、Line、Email、WhatsApp、Zulip 等。适配器均支持动态加载，可轻松扩展自定义适配器。
onebots 支持哪些协议？
onebots 支持 OneBot V11、OneBot V12、Satori V1、Milky V1 四种标准协议。一个账号可同时提供多种协议接口，下游框架可根据需要选择连接任意协议。OneBot V12 是下一代版本，提供更标准化的 message segment 格式、更完整的类型系统、跨平台特性支持和更好的扩展性。
如何安装 onebots？
需要 Node.js >= 22 和 pnpm/npm/yarn 包管理器。全局安装使用 npm install -g onebots 或 pnpm add -g onebots；项目安装使用 npm install onebots 或 pnpm add onebots。安装后根据要接入的平台安装对应适配器如 @onebots/adapter-wechat，根据下游框架支持的协议安装对应协议包如 @onebots/protocol-onebot-v11。
how to start onebots service?
命令行方式（推荐）：onebots -r wechat -p onebot-v11 启动基础服务，或使用 onebots -r wechat -p onebot-v11 -c config.yaml 指定配置文件。可同时启用多个协议：onebots -r wechat -p onebot-v11 -p onebot-v12 -p satori-v1。也可通过代码启动：导入 App 和适配器、注册适配器和协议、创建 App 实例并启动。
什么是 imhelper 客户端 SDK？
imhelper 是 onebots 提供的统一客户端接口 SDK，抹平不同协议的差异。它支持 WebSocket、Webhook、SSE 多种消息接收方式，允许开发者直接使用客户端 SDK 开发跨协议机器人应用，无需关心底层协议差异。通过 createImHelper 和 createOnebot11Adapter 等函数可快速连接 onebots 服务端。
onebots 的端口是多少？
默认 HTTP 服务器端口是 6727，可在 config.yaml 配置文件中通过 port 参数修改。HTTP API 访问地址格式为 http://localhost:6727/{platform}/{account_id}/onebot/v11/{action}，WebSocket 地址格式为 ws://localhost:6727/{platform}/{account_id}/onebot/v11。
如何配置平台账号？
在 config.yaml 配置文件中填写平台机器人的认证信息，格式为 {platform}.{account_id}。例如 wechat.my_wechat_mp 用于微信公众号，qq.3889001676 用于 QQ 机器人。每个账号可配置多个协议，覆盖通用配置。平台特定配置如 AppID、AppSecret、Token 等需根据各平台文档准备。
onebots 适合什么场景？
服务端场景：当你想用 Koishi 等框架开发机器人但平台不直接支持时，onebots 服务端可作为桥梁，将平台 API 转换为标准协议。客户端场景：当你需要开发跨协议的机器人应用时，imhelper 提供统一的客户端接口，无需关心底层协议差异。适合机器人开发者、跨平台需求团队、使用主流机器人框架的用户。
onebots 收费吗？
onebots 是开源免费项目，通过 npm 可免费下载安装使用，没有付费计划或商业版本。所有功能包括所有平台适配器和协议均免费使用。用户只需自行准备平台账号（部分平台可能需要官方审核或付费）并承担服务器部署成本。适配器和协议包按需单独安装也完全免费。