Welcome to Minecraft UniBot. This page walks you through the complete deployment flow from scratch to a working bot; the whole process takes about 10 minutes.

Terminology

Before you begin, let's clarify the following terms to avoid ambiguity later:

Term	Meaning
Core / Implementation	Refers to the UniBot project itself, a NoneBot2 server that actually implements the bot's functionality
Bot	QQ bot, Telegram Bot, etc., referring to the bot accounts created on each platform
Bot protocol client	Some bots (such as QQ) require a forwarding service to connect to the core; that forwarding service is the protocol client. Some platforms don't need this step

Terminology

Deployment Overview

1. Install the bot itself

   Install and start UniBot, see Step 1.

2. Install and configure the QueQiao plugin on the server

   Install the QueQiao plugin on each Minecraft server, see Step 2.

3. Connect chat platforms

   Install and configure the adapter for the corresponding platform, see Step 3.

4. Complete authorization and verify

   Complete authorization through the Quick Start guide card in WebUI, see Step 4.

If you want to first understand the overall architecture and how the components communicate, refer to Architecture Overview.

Prerequisites

Component	Requirement
Python	3.11+
Package manager	UV (recommended) or pip
Minecraft server	Fabric / Forge / Spigot / Paper / MCDR, etc., with the QueQiao plugin already installed
Chat bot account	QQ bot, Telegram Bot, etc.

Prerequisites

Step 1: Install UniBot

Script Installation (Recommended)

Download the one-click installation script for your platform from the Releases page:

Platform	Script
Windows	Install.bat, just double-click to run; it automatically installs uv, clones the repository, configures WebUI, and syncs dependencies
Linux / macOS	Install.sh, first run chmod +x Install.sh, then run ./Install.sh

One-Click Installation Script

The script will automatically: detect and install UV, pull the repository for the corresponding version, ask whether to enable WebUI, and run uv sync to sync dependencies.

Note

After installation, the script will generate a Start.sh or Start.bat in the UniBot directory; you only need to run it to start the core.

To start manually, just run uv run Watchdog.py in the root directory.

With WebUI, you'll basically never need to manually edit the configuration afterward. After starting, open http://<ip>:<port>/ in your browser (default http://127.0.0.1:8000/webui). On first visit, follow the prompts to initialize the admin account, then you can configure chat platforms, manage servers, and view logs in WebUI.

Just follow the guide to complete the entire configuration flow quickly — no need to manually edit .env or Config.toml, and no need to consult the documentation.

Note

A full introduction to WebUI's features (detailed page explanations, Config Center, log viewing, token authorization, etc.) is available in the WebUI Admin Panel.

Manual Installation (Optional)

# Clone the project and create a virtual environment
git clone https://github.com/MineJPGcraft/UniBot
cd UniBot

# Install the core and WebUI dependencies
uv sync --extra webui

# Start the bot
uv run Watchdog.py

You can also install with pip + venv, see the Configuration Guide for the exact commands, but uv is recommended for management.

Docker Installation

After installing Docker, run the following in a terminal

docker run -d -p 8000:8000 ghcr.io/minejpgcraft/unibot:latest

UniBot will start running in the background

Docker Compose Installation

After installing Docker and Compose, run

git clone https://github.com/MineJPGcraft/UniBot
cd UniBot
docker compose up -d

Step 2: Install and Configure QueQiao

Every Minecraft server needs to have the QueQiao plugin/mod installed to connect to the core.

After installation, you also need to configure it so the server and the bot can establish a connection and communicate normally. For detailed installation methods and plugin download links, refer to the Minecraft Adapter, and choose the installation mode that fits your needs.

Step 3: Connect Chat Platforms

In addition, you need to install and configure the corresponding adapter so that the bot account can connect to the core.

For the specific configuration items of each platform's adapter, refer to the Configuration Guide.

Step 4: Verify Startup

After completing Step 2 and Step 3, you can authorize and verify.

Token Authorization

Log in to the WebUI dashboard and click Token Authorization in the "Quick Start" guide card to complete superuser authorization (you can also send the authentication token printed in the console in a group chat on any platform).

Note

The complete explanation of token authorization (steps, the one-time-use and auto-refresh token mechanism, and how to authorize without WebUI) is available in WebUI Admin Panel · Token Authorization.

Verify Features

After authorization, the guide card collapses automatically. Now send the following in a chat group:

/help

If everything is normal, the bot will return the available command list, and you can start using it. Then send /server to view the currently online, connected servers.

FAQ

• Bot not responding to commands? Check the COMMAND_START prefix, whether command_groups contains the current group, and whether SUPERUSERS includes your account.
• Can't connect to the server? Confirm that the access_token on both ends matches, that the WebSocket address and port are reachable, and check the MCDR and bot logs.

For more configuration items, see Configuration Guide.

Contributors: LonelySail

Previous pageGuide

Next pageFeatures