🚀 MaiBot Quick Start

Updated: 07/22/2026Word count: 0 wordsReading time: 1 min

Welcome to MaiBot! This guide will walk you through getting MaiBot up and running from scratch.

📋 Prerequisites

You'll need these 3 things ready:

1️⃣ A QQ Side Account 🆔

• Must be a side account (bot accounts risk being restricted — don't use your main account)
• Must be able to log in normally (test it on your phone first)

2️⃣ An AI Model API Key 🔑

MaiBot needs a Large Language Model (LLM) to think and reply. The first launch generates a default configuration using DeepSeek. The minimum runnable setup needs only a working DeepSeek API key; vision and embedding models can be added later.

Provider	Price	Features	How to Get
Alibaba Cloud Bailian (Qwen)	Low	Provides Qwen and other model capabilities	Bailian Console → API-KEY
SiliconFlow	Low	200+ models aggregated (DeepSeek, Qwen, GLM, etc.), one API key for text/vision/embedding, Alipay/WeChat Pay	Sign up
DeepSeek 🏆 Default	Very Low	Default text-model provider and the shortest first-time setup	Sign up
Zhipu AI (GLM)	Free+	Tsinghua-backed, text/vision/embedding fully supported; Flash series permanently free, 20M free tokens for new users	Zhipu Platform
Kimi (Moonshot)	Medium	262K context window, native multimodal (text+image+video), excellent bilingual capability	Sign up

💡 For Beginners

• Want to get running first? Use DeepSeek — enter the API key and verify the text models in the WebUI wizard
• Need vision or related memory features? Add them later — vision and embedding are not first-run requirements
• Want free? Use Zhipu GLM — Flash models are permanently free, plus 20M welcome tokens
• Most providers offer free trial credits — try before you commit

3️⃣ Git

MaiBot uses Git for code management. Download from git-scm.com.

---

🏃‍♂️ Installation Steps

Step 1: Download MaiBot 📥

Option A: Download ZIP (Recommended for Windows beginners)

1. Go to MaiBot Releases
2. Find the latest version, expand Assets, download Source code (zip)
3. Extract the zip file to a convenient location (e.g. your desktop)

Option B: Git Clone (if you have Git installed)

Bash

git clone https://github.com/Mai-with-u/MaiBot.git

To use the development branch:

Bash

git checkout dev

Step 2: Install Python 🐍

MaiBot requires Python 3.12+ (Python 3.12 / 3.13 recommended).

1. Go to python.org and download the Windows installer
2. Check "Add Python to PATH" during installation
3. Open Command Prompt (Win + R → type cmd → Enter) and verify:

Bash

python --version

Step 3: Install uv (Package Manager) 📦

MaiBot uses uv for dependency management — much faster than pip.

In Command Prompt:

Bash

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close and reopen Command Prompt after installation.

Step 4: Install Dependencies

Navigate to the MaiBot folder (in File Explorer, type cmd in the address bar) and run:

Bash

uv sync

This creates a virtual environment (.venv) and installs all dependencies (takes a few minutes).

💡 For users in China

MaiBot's pyproject.toml is pre-configured with the Tsinghua mirror — uv sync will use it automatically.

Step 5: First Launch (Generate Config + Accept License)

Bash

uv run python bot.py

On the first launch, you'll be prompted to accept the EULA and Privacy Policy. Type 同意 (or confirmed) and press Enter. The system generates default files in config/ and continues initializing MaiBot and WebUI; a second launch is not required just to generate configuration.

💡 Server / Headless Environments

If deploying on a server without an interactive terminal and you can't type "agree", use environment variables to skip the prompt:

# Run once to see the required hash values
uv run python bot.py
# Copy the EULA_AGREE=xxx and PRIVACY_AGREE=xxx shown in terminal
# Then set them and restart
export EULA_AGREE=<hash shown>
export PRIVACY_AGREE=<hash shown>
uv run python bot.py

Step 6: Enter WebUI

As the same process continues, you'll see logs like:

🌐 WebUI server starting...
🌐 Access address: http://127.0.0.1:8001
🔑 WebUI Access Token: e7b2a4f1... (long string)
💡 Open the access address in your browser and enter the token to log in

Step 7: Open WebUI & Complete Setup 🌐

1. Open your browser and go to http://127.0.0.1:8001
2. You'll see a login page — enter the Access Token shown in the terminal
3. After logging in, the setup wizard will appear automatically for first-time users
4. Enter your DeepSeek API key and verify that the text models used for reply, planning, and utility tasks are available
5. The system marks initialization as complete, and you're in the normal dashboard

You can skip vision and embedding models and configure them later when those capabilities are needed.

💡 All configuration is done through WebUI

You can change nickname, personality, chat frequency, and models in Config Management without editing files manually. Most runtime settings hot-reload; listeners, MCP connections, and other startup settings still require a restart. See the Configuration Overview.

📱 Connect to QQ

After MaiBot core starts, you need to connect it to QQ using NapCat.

Install NapCat

Follow the NapCat Official Installation Guide to install and log in with your QQ side account.

Install the NapCat Adapter

In the MaiBot WebUI (browser at http://127.0.0.1:8001):

1. Click "Plugin Management" in the left sidebar
2. Search for "NapCat Adapter"
3. Click Install

After installation, configure the connection address following the adapter's instructions.

⚠️ Important: Plugins Are Disabled by Default

Whether installed via WebUI or manually cloned to plugins/, the adapter plugin is DISABLED by default. Installation alone does NOT make it work!

You must go to the WebUI "Plugin Management" page, find the NapCat Adapter, and manually toggle the enable switch.

Alternatively, find the plugin's actual directory and change [plugin] enabled to true in its config.toml. The file watcher normally loads it without restarting MaiBot; directory names can vary by installation method.

How to verify? Check the startup logs: "activated" means enabled, "disabled, skipping activation" means still disabled.

💡 More Details

See the NapCat Adapter Guide for complete installation and configuration instructions.

---

🎉 Start Chatting

Test Your Bot

In a QQ group, @your bot, or send a private message:

@MaiMai Hello!

If the bot replies, congratulations — you're all set! 🎉

---

🆘 Troubleshooting

Bot exits immediately on start?

Check the logs by running:

Bash

uv run python bot.py

MaiBot continues after generating its default files. If it exits unexpectedly, use the final log error as the source of truth and check agreement confirmation, TOML syntax, port binding, and dependency initialization.

Port conflict?

If you see an error like this on startup:

WebUI server failed to start: port 8001 is already in use (host=127.0.0.1)

The default port is occupied by another program.

Solution 1: Change the port

Edit config/bot_config.toml, modify the port in the [webui] section:

TOML

[webui]
port = 8002   # Change to an unused port like 8002, 8003

Restart and the WebUI will be available at http://127.0.0.1:8002.

💡 If the legacy maim_message WebSocket port (default 8000) is also taken, change ws_server_port to a different unused port, such as 18000. The NapCat plugin adapter does not use this service.

Solution 2: Kill the process using the port

Bash

# Windows (CMD)
netstat -ano | findstr :8001
# Note the PID in the last column, then:
taskkill /PID <PID> /F

# Linux/macOS
lsof -i :8001
# Note the PID, then:
kill -9 <PID>

Restart MaiBot after freeing the port.

Bot not responding?

Check in order:

1. ✅ Is NapCat online? (NapCat interface shows logged in)
2. ✅ Is the API key correct? (check in WebUI config)
3. ✅ Is the adapter plugin installed? (check in WebUI plugin management)
4. ✅ Any errors in the logs? (check WebUI log viewer)

"API key invalid"?

• Make sure there are no extra spaces
• Verify you selected the right provider
• Confirm your account still has credits

Can't access the WebUI?

• Confirm MaiBot is running (terminal window is open)
• Check the address: http://127.0.0.1:8001
• Check your firewall settings

How to change settings?

• Via WebUI: Open http://127.0.0.1:8001 in your browser and use the config editor
• Edit files directly: Modify config/bot_config.toml or config/model_config.toml
• Most changes apply instantly — MaiBot supports hot-reloading of configuration

---

🎯 What's Next

You've successfully deployed MaiBot! Now you can:

• 📚 Configuration Guide — Tweak personality, chat frequency, memory, and more
• 🔌 Plugin Development — Build new features for MaiBot
• 🧠 Understand MaiBot's Brain — Dive into the reasoning engine
• 💬 Invite MaiBot to more groups — Share the fun with friends

---

Having issues? Join the community QQ group: MaiBrain EEG

Have fun!