Gateway & Network Transport
Relevant source files
The following files were used as context for generating this wiki page:
The OneBots gateway manages communication between multiple IM platforms and downstream bot clients using standardized wire protocols. It acts as a central hub that normalizes platform-specific events into a unified format and exposes them via various network transport methods such as HTTP, WebSocket, and Server-Sent Events (SSE). Sources: README.en.md:16-25, AGENTS.md:10-15
The network transport layer operates within the packages/onebots application, which hosts a Koa-based HTTP/WS server to handle routing, configuration, and real-time event delivery. Sources: AGENTS.md:41-45, architecture.html:105-115
System Architecture Overview
The system architecture follows a layered approach to separate IM platform integration from client-facing protocol delivery.
The diagram shows the data flow from platform events through the normalized gateway layers to the various network transport methods. Sources: README.en.md:32-45, architecture.html:100-140
Supported Transport Methods
OneBots supports multiple communication modes to accommodate different downstream client requirements. The following table summarizes the primary transport methods per protocol:
| Protocol | HTTP API | Forward WebSocket | Reverse WebSocket | Webhook / SSE |
|---|---|---|---|---|
| OneBot v11 | Server (POST) | Server | Client | Webhook (Client) |
| OneBot v12 | Server (POST) | Server | Client | Webhook (Client) |
| Satori v1 | Server (POST) | Server | Not supported | Webhook (Client) |
| Milky v1 | Server (POST) | Server | Client | SSE (Server) / Webhook |
Sources: architecture-diagrams.md:240-278, tests/README.md:140-155
WebSocket Transport
OneBots utilizes WebSocket transport for real-time, bidirectional communication.
- Forward WebSocket: The gateway acts as a server. Clients connect to a specific URL (e.g.,
/qq/{account_id}/onebot/v11) to receive events and call APIs. Sources: architecture.html:185-200 - Reverse WebSocket: The gateway acts as a client. It initiates a connection to a remote URL specified in the
config.yamlfile to push events and receive API calls. Sources: tests/README.md:120-135, architecture-diagrams.md:245-250
HTTP & Webhook Transport
- HTTP API: Standard REST-like endpoints allow clients to call platform actions. POST requests typically require
application/jsoncontent types. Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:85-90 - Webhook (HTTP Reverse): The gateway pushes platform events to a configured URL via POST requests. OneBot v11 implementations may include an
X-Signatureheader for HMAC validation. Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:28-30
Authentication & Security
Authentication is performed during the transport handshake or on every request depending on the method used. The gateway validates tokens before allowing access to protocol features. Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:15-25
Authentication Methods
- Authorization Header: Most protocols prioritize the
Authorization: Bearer <token>header. Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:55-60 - Query Parameters: For environments where headers cannot be set (e.g., some WebSocket clients), a
?access_token=<token>query parameter is accepted. Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:65-70
Sequence diagram for WebSocket authentication during the protocol upgrade phase. Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:23-26, architecture.html:260-275
Observability Endpoints
The gateway provides dedicated transport routes for monitoring the health and performance of the system. These endpoints are typically exposed on the management port (default 6727). Sources: packages/core/src/app-observability.ts:240-250, AGENTS.md:95-100
/health: Returns the current process status, uptime, and version information./ready: Returns a detailed readiness snapshot. It checks if all adapters are online and all protocol instances are ready./metrics: Provides Prometheus-compatible metrics, including memory usage, active WebSocket connections, and protocol status.
Sources: packages/core/src/app-observability.ts:240-360
Readiness Logic
A gateway is considered "ready" only if:
- The server is started and not currently reloading.
- Configuration is in sync with the disk.
- All accounts are online.
- All configured protocol outlets have achieved a
readylifecycle status.
Sources: packages/core/src/app-observability.ts:88-115
Conclusion
The Gateway & Network Transport system in OneBots ensures that IM events and API actions are delivered reliably across diverse network environments. By supporting both server-side and client-side communication (Forward/Reverse) and implementing standardized authentication, it provides a flexible infrastructure for bot developers. Sources: README.en.md:10-15, architecture-diagrams.md:12-30