Getting Started Guide
Relevant source files
The following files were used as context for generating this wiki page:
OneBots serves as a multi-platform and multi-protocol IM bot gateway and framework built with TypeScript and Node.js. It allows a single process to communicate with multiple IM platforms (such as QQ, WeChat, and Discord) while exposing standard protocols (OneBot, Satori, or Milky) to downstream applications or plugins. The system utilizes a unified CommonEvent abstraction to ensure that internal logic remains consistent regardless of the platform source.
Sources: README.en.md:3-8, AGENTS.md:7-14
Prerequisites
You must install specific tool versions to ensure compatibility with the OneBots monorepo.
| Tool | Minimum Version | Recommended / Locked Version |
|---|---|---|
| Node.js | >= 24 | 24 (See .node-version) |
| pnpm | >= 10.34.5 | 10.34.5 (Locked in project) |
| TypeScript | 5.x | 5.9.3 (Managed via catalog:) |
Sources: CONTRIBUTING.md:13-20, AGENTS.md:25-32
Deployment Methods
OneBots supports three primary installation methods: Docker, npm package, or building from source.
A. Docker (Recommended)
Docker provides a persistent manager that controls a separate gateway process. You must mount a host directory to /data to store configuration, device sessions, and runtime data.
docker run -d -p 6727:6727 -v $(pwd)/data:/data --name onebots ghcr.io/lc-cn/onebots:master
Sources: README.en.md:58-62, deploy/1panel/onebots/README_en.md:6-10
B. npm Installation
You can install the management program directly via npm. This method involves installing the manager, registering it as an OS service, and starting the management console.
pnpm add onebots
npx onebots install --data-dir ./data
npx onebots start
Sources: README.en.md:66-72
C. Building from Source
For development, you must build the core packages first because internal dependencies rely on the lib/ output of these packages.
- Clone the repository.
- Install dependencies:
pnpm install. - Build core packages:
pnpm build:packages. - Run full build:
pnpm build. - Start dev environment:
pnpm dev.
Sources: CONTRIBUTING.md:24-40, AGENTS.md:64-70
Initial Setup and Pairing
OneBots uses a device-pairing security model. The management console remains available even if the gateway is stopped or fails.
- Bootstrap: Generate a one-time device code from the host to pair your browser.
- CLI:
npx onebots auth bootstrap --data-dir ./data - Docker:
docker exec --user 1000:1000 onebots node /app/packages/onebots/lib/bin.js auth bootstrap --data-dir /data
- CLI:
- Access UI: Open the management address (default port 6727) and enter the pairing code within five minutes.
- Install Dependencies: Use the Web UI to select platform adapters (e.g., QQ, Telegram) and output protocols (e.g., OneBot v11).
- Configure: Create account settings in the management console and validate the configuration.
- Activate: OneBots installs required peers into an immutable runtime generation and activates it after confirmation.
Sources: README.en.md:74-84, deploy/1panel/onebots/README_en.md:12-20
System Architecture
The following diagram illustrates how OneBots bridges IM platforms to downstream consumers.
The architecture separates platform-specific events from standardized protocol exports.
Sources: README.en.md:25-42, architecture-diagrams.md:14-72
Core Development Workflow
If you are contributing to the project, follow the monorepo structure and testing guidelines.
Monorepo Layout
packages/core: Core abstractions (Adapters, Protocols, ID mapping).packages/onebots: CLI, Gateway, and main Application logic.adapters/*: Platform-specific integrations (e.g.,@onebots/adapter-qq).protocols/*: Outbound protocol implementations (e.g.,@onebots/protocol-onebot-v11).
Sources: CONTRIBUTING.md:46-88, AGENTS.md:46-60
Essential Commands
| Command | Description |
|---|---|
pnpm build:packages | Builds core packages (required first). |
pnpm dev | Starts management service in development mode. |
pnpm test | Runs unit tests using Vitest. |
pnpm changeset | Creates a versioning changeset for publishing. |
Sources: CONTRIBUTING.md:230-250, AGENTS.md:63-78
Coding Standards
- ES Modules: Always include the
.jsextension in relative imports. - Logging: Use
this.logger.xxx()instead ofconsole.log. - Error Handling: Wrap unknown errors using
ErrorHandler.wrap()and catch variables aserror. - Typing: Avoid
any; useunknownwith type guards for external SDK results.
Sources: CONTRIBUTING.md:94-175, AGENTS.md:105-132, packages/core/ARCHITECTURE.md:4-22
Summary
To get started with OneBots, ensure your environment meets the Node.js 24 and pnpm 10 requirements. Deploy via Docker for the simplest setup, then use the auth bootstrap command to access the Web UI for adapter and protocol configuration. When developing, remember to build the packages/core first to satisfy monorepo dependencies.
Sources: README.en.md:95-102, AGENTS.md:155-158