WebUI Admin Panel

About 1741 wordsAbout 6 min

WebUI is UniBot's built-in modern web admin panel, built on Vue 3 + Vite + Pinia + reka-ui, interacting with the backend through a REST API and WebSocket.

It provides visual configuration, real-time monitoring, server / player management, log viewing, and more, and is the primary entry point for daily use of UniBot. With WebUI, you'll basically never need to manually edit configuration files — deployment and maintenance are done entirely in the browser.

Features at a Glance

View	Features
Dashboard	Real-time running status, memory/CPU usage, online server count, bound player count; the "Quick Start" guide card at the top
Servers	View the status of all connected servers and online players; enter the details page to execute commands remotely
Player Management	Manage whitelist bindings, associating platform users with game IDs
Adapters	View / install / enable / configure communication adapters for each platform (Minecraft, OneBot V11, etc.)
Plugin Management	View the list of loaded NoneBot2 plugins and their enable/disable status
Extension Management	Manage UniBot extensions: enable/disable, configure, switch rendering engines and templates, and access the extension marketplace
Config Center	Visually edit `Config.toml`, `.env`, `Messages.toml` and extension settings, with Schema validation, grouped display, and source mode support
Log Viewer	Real-time scrolling view of runtime logs, with file switching and level filtering
User Management	Manage WebUI login accounts, roles, and permissions
Personal Settings	View the current account info, change your password
Login Authentication	JWT + password authentication (HttpOnly Cookie); first visit guides you through initializing the admin account

WebUI Main Features

Enable and Access

Prerequisites

The WebUI dependencies must be installed first, and WebUI must be enabled in Config.toml:

# Install webui dependencies (required for both the install script and manual deployment)
cd UniBot
uv sync --no-dev --extra webui

[webui]
enabled = true

Warning

WebUI cannot be enabled if the dependency installation above hasn't been run, please make sure the dependencies are installed first.

Startup and Access

Start the bot: uv run Watchdog.py.
On the first start, the bot will automatically download the WebUI static assets matching its own version from GitHub Releases and mount them.
Open http://<your-ip>:<PORT>/webui in your browser (default http://127.0.0.1:8000/webui).

Initialize the Admin

Complete initialization on your first visit: the page will guide you through creating an admin account (username + password). Once created, you can log in and enter the dashboard.

Note

The admin account protects WebUI's management features. For multi-user collaboration, you can create more accounts in "User Management".

Page Details

Dashboard

After logging in, you land on the dashboard by default, showing the bot's real-time running status:

Top status bar: connection status, online server count, online player count, memory / CPU usage.
"Quick Start" guide card: a progress checklist running through the entire deployment process; the three steps auto-detect their completion status:
1. Connect a chat platform — completes automatically once an enabled chat platform adapter is detected;
2. Connect a Minecraft server — completes automatically once a server is connected (an online server exists or a WS address is configured);
3. Add a superuser — completes automatically once SUPERUSERS is non-empty.
When all steps are complete, the card collapses automatically; it can also be collapsed manually (the state is remembered in browser local storage).
Server overview: a quick overview of the online status of all connected servers.

Quick Start Guide Card

The "Quick Start" guide card is the deployment progress checklist at the top of the dashboard; the completion status of the following three steps is determined fully automatically:

Connect a chat platform
Completes automatically once a QQ / Telegram or other platform adapter is installed and enabled; click to jump to the adapter management page.
Connect a Minecraft server
Completes automatically once a server is connected through the QueQiao plugin (an online server exists, or a WebSocket address is configured); click to view the QueQiao installation documentation.
Add a superuser
Set an admin to use admin commands; click the "Token Authorization" button on the right to complete authorization quickly.

Once all three steps are complete, the card collapses automatically. This card is just a visual checklist of deployment progress, mapping one-to-one to the steps of the deployment documentation:

Guide Card Step	Corresponding Documentation Section
Connect a chat platform	Quick Start · Step 3
Connect a Minecraft server	Quick Start · Step 2
Add a superuser	Quick Start · Step 4

Tips

The completion status of the guide card is detected automatically by WebUI (online adapter present / online server present / SUPERUSERS non-empty), no manual checking required.

Token Authorization

In the "Add a superuser" step of the guide card, click Token Authorization; the dialog will show the currently valid authentication token:

Copy the token and send it in a group chat on any platform;
The bot completes the authorization automatically: it adds the current group to the message groups and command groups (message_groups / command_groups), and sets the sender as a superuser (SUPERUSERS);
The token is one-time-use and auto-refreshing: it refreshes immediately after a single use, and the old token is invalidated.

Authorization without WebUI is also possible

Every time the bot starts, it prints the current token in the console (in the form 认证令牌：A1B2C3D4E5), and sending it in a group chat on any platform completes the same authorization.

Afterwards, you can also add superusers manually in the Config Center of WebUI.

Server Management

Server list: view the connection status, type, and online status of all servers.
Server details: view a single server's online players, server type, and status details, and execute commands remotely (send commands to the server console).

Player Management

Manage blacklist / whitelist bindings: associate platform users (such as QQ numbers) with game IDs, with support for searching and adding / unbinding.

Adapter Management

View installed platform adapters (Minecraft, OneBot V11, etc.).
Install / enable / disable / configure adapters.
Core adapters (such as Minecraft) are marked as protected and cannot be operated on.

Note

When you install a platform adapter through WebUI, UniBot automatically handles dependency installation and registration. See Connect Chat Platforms.

Plugin Management

View the list of loaded NoneBot2 plugins and their enable/disable status. All plugins come from the official plugin registry; after installation, refer to the plugin's GitHub documentation and configure the parameters yourself in .env.

Extension Management

The management entry for the UniBot extension system (requires admin permissions):

View all installed extensions and their status (enabled / disabled / isolated).
Adjust extension business configuration (forms are generated dynamically based on the model's JSON Schema).
Switch rendering engines and templates (template switching takes effect immediately).
Access the extension marketplace to search and one-click install / upgrade / uninstall extensions.

See the "WebUI Management" section in Extension System.

Config Center

Config.toml: config items displayed in groups, with Schema validation; save after editing and (as needed) restart.
.env: environment variables displayed in groups (including bot card editing for bot list fields such as QQ_BOTS, TELEGRAM_BOTS, etc.); saving changes requires restarting the bot to take effect.
Messages.toml: edit message template text.
Extension settings: edit every extension that declares configuration options (including no-code template packs) in one place; changes take effect immediately, and disabled or blocked extensions are read-only.
Source mode is also available, for editing TOML / env sources directly.