Core Concepts & Glossary

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• architecture-diagrams.md
• CONTRIBUTING.md
• README.en.md
• architecture.html
• packages/core/ARCHITECTURE.md
• packages/core/src/app-observability.ts
• tests/PROTOCOL_AUTH_HEARTBEAT.md

OneBots is a multi-platform, multi-protocol instant messaging (IM) bot gateway and framework built with TypeScript and Node.js. It functions as a self-hosted IM middleware that centralizes configuration, authentication, and lifecycle management for various IM bots. The system isolates the management service from the gateway process to ensure the management interface remains available even if the gateway fails.

The framework resolves the problem of glue code redundancy by providing a unified internal event model called CommonEvent. This allows one bot process to communicate with multiple IM platforms simultaneously while exposing standard wire protocols to downstream consumers or plugins.

Sources: AGENTS.md:8-15, README.en.md:14-22

System Architecture

The OneBots architecture consists of four distinct layers that handle the transformation of platform-specific data into standardized protocol outputs.

This diagram shows the flow from raw platform events to standardized protocol exports.
Sources: README.en.md:27-40, architecture-diagrams.md:16-56

Component Glossary

Term	Definition
Adapter	Maps platform-specific events and APIs to the CommonEvent format and shared Adapter APIs.
Protocol	Converts CommonEvent into standard wire formats (e.g., OneBot v11/v12, Satori) and handles inbound API calls.
Account	Represents a specific bot identity on a platform (e.g., a specific QQ number or WeChat ID).
CommonEvent	A unified abstraction of IM events (messages, notices, requests) used internally by the framework.
id_map	A system for mapping between platform-specific raw IDs and standardized internal string identifiers.
BaseApp	The core application class providing logging, routing, and lifecycle management.

Sources: README.en.md:20-25, AGENTS.md:21-26, CONTRIBUTING.md:103-107

Data Flow Mechanisms

The system processes data through two primary pipelines: Uplink (Ingress) and Downlink (Egress).

Ingress: Receiving Events

Adapters receive raw events from platform SDKs (e.g., via WebSockets or Webhooks). The Adapter extracts the relevant data and converts it into a CommonEvent. The Account then dispatches this event to all active Protocol instances, which format the data according to their specific standards (like OneBot v11) before pushing it to downstream clients.

This diagram illustrates how platform events are normalized and distributed to multiple protocol clients.
Sources: architecture-diagrams.md:113-146, architecture.html:200-220

Egress: API Calls

Downstream clients call APIs via HTTP or WebSocket endpoints (e.g., /send_private_msg). The Protocol layer validates the request and authentication tokens. It then converts the standardized parameters into platform-specific formats and calls the Adapter's implementation methods.

Sources: architecture.html:230-264, architecture-diagrams.md:155-190

Core Kernel Systems

The @onebots/core package provides the essential infrastructure for the framework.

Error Handling System

OneBots uses a structured error hierarchy to categorize failures. The ErrorHandler.wrap() function ensures unknown errors are transformed into categorized OneBotsError types.

Category	Description
NETWORK	Failures related to connectivity or timeouts.
CONFIG	Issues with config.yaml or schema validation.
VALIDATION	Inbound API parameter or data structure errors.
PROTOCOL	Errors within the protocol conversion or wire format layer.
ADAPTER	Failures in the underlying platform SDK or API calls.

Sources: packages/core/ARCHITECTURE.md:5-20, CONTRIBUTING.md:164-177

Observability and Readiness

The system tracks the health of all components through a readiness snapshot. A system is considered "Ready" only if all adapters are online, all protocols are initialized, and the configuration is synchronized with the disk.

export interface ReadinessSnapshot {
    ready: boolean;
    timestamp: string;
    server: boolean;
    reloading: boolean;
    runtime_operation: RuntimeOperation;
    configured: boolean;
    adapters: Record<string, AdapterReadinessCounts>;
}

Sources: packages/core/src/app-observability.ts:68-84, packages/core/src/app-observability.ts:100-105

ID Mapping

To ensure cross-platform compatibility, all platform raw IDs must be normalized.

• Ingress: Use this.createId(rawId) to normalize platform IDs into the internal CommonTypes.Id type.
• Egress: Use resolveId to convert internal IDs back into the format expected by the specific IM platform.

Sources: AGENTS.md:280-283, CONTRIBUTING.md:103-107

Lifecycle and Runtime

The BaseApp manages the lifecycle of all services. During the stop() sequence, the LifecycleManager ensures all resources (database connections, HTTP servers, IMAP pollers) are gracefully shut down.

When configuration changes occur, the management service initiates a RuntimeOperation. During these operations (like configuration_reload), the gateway temporarily withdraws its "Ready" status until the new configuration is successfully applied.

Sources: packages/core/ARCHITECTURE.md:104-125, packages/core/src/app-observability.ts:153-164

Authentication and Connectivity

Communication between clients and the gateway is secured via standard authentication patterns.

• OneBot 11/12: Supports access_token via the Authorization: Bearer <token> header or access_token query parameter.
• Milky: Requires Authorization: Bearer <token> for API calls.
• Satori: Uses Bearer Token authentication.
• Heartbeats: Protocols like OneBot 11/12 emit meta_event heartbeats containing an interval (in milliseconds) to signal status to clients.

Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:25-35, tests/PROTOCOL_AUTH_HEARTBEAT.md:55-65

OneBots effectively abstracts complex IM platform interactions into a manageable set of core components, ensuring that developers can focus on bot logic rather than infrastructure glue.