Introduction to OneBots
Relevant source files
The following files were used as context for generating this wiki page:
OneBots is a multi-platform and multi-protocol Instant Messaging (IM) bot gateway and framework built with TypeScript and Node.js. It functions as a self-hosted IM bot middle-end and protocol exit, allowing one process to communicate with multiple IM platforms while exposing standard protocols to plugins or backend services.
The system solves the problem of cross-platform glue code by providing a unified CommonEvent abstraction. This architecture enables developers to run multiple protocols, such as OneBot and Satori, on the same account simultaneously.
Sources: README.en.md:5-15, AGENTS.md:12-18
System Architecture
OneBots employs a layered architecture that decouples platform-specific logic from wire protocol communication. The system consists of four primary layers: the Adapter layer, the Core layer, the Protocol layer, and the Application layer.
Architectural Layers
| Layer | Responsibility |
|---|---|
| Adapter | Maps platform-specific events and APIs to CommonEvent and shared Adapter APIs. |
| Protocol | Converts CommonEvent into wire formats like OneBot v11/v12, Satori, or Milky. |
| Core (@onebots/core) | Manages accounts, ID mapping, routing, loggers, and the registry system. |
| App (onebots) | Handles configuration, plugin loading, and provides the HTTP/WS gateway and Web UI. |
Sources: README.en.md:26-33, AGENTS.md:19-27
High-Level Architecture Flow
This diagram illustrates the relationship between IM platforms, the internal OneBots components, and downstream consumers.
Sources: README.en.md:38-51, architecture.html:98-120
Core Components
1. Adapter Layer
The Adapter layer normalizes incoming events from various IM platforms into a standard structure. Each adapter, such as adapter-qq or adapter-telegram, implements a specific platform's API and event handling logic.
2. Protocol Layer
The Protocol layer provides the communication interface for downstream clients. It supports multiple inbound API calling methods, including HTTP, WebSocket, WebHook, and Reverse WebSocket.
3. Account and ID Management
The Account layer manages the lifecycle of individual platform accounts. It uses an ID map (createId and resolveId) to maintain consistency between internal identifiers and platform-specific raw IDs.
Sources: AGENTS.md:19-27, architecture.html:125-140
Class Relationships
The following class diagram represents the internal hierarchy and management structure of the core classes.
Data and Event Flow
OneBots processes data in two directions: Upstream (from platforms to clients) and Downstream (from clients to platforms).
Upstream: Event Dispatching
When an IM platform sends a message, the Adapter extracts the data and transforms it into a CommonEvent. The Account instance then dispatches this event to all active Protocol instances associated with that account.
Downstream: API Execution
When a client calls an API (e.g., send_private_msg), the Protocol validates the request and converts the parameters into the format required by the Adapter. The Adapter then executes the action via the platform's SDK.
Technical Stack and Requirements
OneBots is built as a pnpm monorepo using modern JavaScript/TypeScript standards.
| Component | Technology / Requirement |
|---|---|
| Language | TypeScript (Strict mode) |
| Runtime | Node.js >= 24 |
| Package Manager | pnpm >= 10.34.5 |
| Module System | ESM (Pure ES Modules) |
| Web UI | Vue 3 + Vite + Tailwind CSS |
| Database | SQLite (via @onebots/core) |
Sources: AGENTS.md:32-48, CONTRIBUTING.md:28-35
Management and Lifecycle
The system utilizes a persistent Management Service that controls a separate Gateway Process. This separation ensures that the Web management console remains available even if the gateway stops or encounters configuration errors.
Configuration Structure
Configuration is stored in config.yaml. Platform-specific settings are keyed by {platform}.{account_id}, while shared protocol settings reside in the general section.
plugins:
adapters: [qq]
protocols: [onebot-v11]
general:
onebot.v11:
access_token: "protocol-token-here"
qq.my_bot:
appid: "123456"
secret: "platform-secret"
Sources: packages/onebots/README.md:12-25, packages/onebots/README.md:95-120
Security and Authentication
The management console does not use the access_token defined in the business configuration. Instead, it employs device code pairing and revocable browser sessions. You must use the CLI command onebots auth bootstrap to generate a one-time code for initial management access.
Sources: packages/onebots/README.md:42-55, deploy/1panel/onebots/README_en.md:12-22