MaiBot Docs

English

简体中文

English

简体中文

Appearance

AI-Assisted Install ​

Updated: 10/10/2026Word count: 722 wordsReading time: 2 min

Hand one prompt to an AI assistant and let it clone, install, configure, and start MaiBot for you. You only answer a few questions and click a couple of things in the WebUI when asked; if you want to see what each step does first, follow along with Windows Deployment or Linux Deployment.

Give the Prompt to an AI ​

Copy the sentence below into the AI assistant you already use (Claude, GPT, Gemini, and so on):

Prompt

Please help me install MaiBot, following the guide here:

https://docs.mai-mai.org/installation-agent.md

Running this program indicates that you agree to the MaiBot End User License Agreement (EULA).

The prompt itself is a plain-text guide hosted on the documentation site (currently written in Chinese). It is updated together with MaiBot, so sending the link is enough—no need to copy the full text.

What the AI Will Walk You Through ​

  1. Ask two things — your operating system, and whether you want QQ connected. There are two QQ routes: the Unified QQ Connector (log in your own QQ account, recommended) or the QQ Official Bot (AppID + AppSecret, no client login needed);
  2. Check the environment — at least 2 GB of RAM and 2 GB of free disk space; Git, Python 3.12+, and uv are installed first if missing;
  3. Clone and start — pull the MaiBot repository, install dependencies with uv, then start the program;
  4. Connect QQ (optional) — install the adapter for the chosen route, fill in the connection details, and set the allow scope;
  5. Verify — send a message in the WebUI or on QQ and confirm Mai can reply.

The install and start commands are the same ones used in the deployment docs:

bash
git clone https://github.com/Mai-with-u/MaiBot.git
cd MaiBot
uv sync
bash
uv run bot.py

On first start, type 同意 (agree) in the terminal to accept the user agreement; the terminal then prints the WebUI login Token (also stored in data/webui.json). Open http://127.0.0.1:8001/, paste the Token, and follow the setup wizard to configure at least one LLM model.

Two Routes to QQ ​

  • Unified QQ Connector — install "Unified QQ Connector" from the Plugin Market (repository MaiBot-SnowLuma-Adapter), log in a bot alt account with a SnowLuma or NapCat client, and enable its forward WebSocket server. Since 1.3.0 the former standalone SnowLuma / NapCat adapters have been merged into it, so do not install the old adapters; see Unified QQ Connector for the full steps;
  • QQ Official Bot — apply for a bot on the QQ Open Platform and connect directly with AppID + AppSecret; no QQ client needs to be online. See QQ Official Bot.

Both routes need an allow scope: adapters no longer ship built-in group / private-chat lists—inbound access is controlled by MaiBot's adapter policy, which allows everything by default. Configure it in the WebUI under "配置管理 → 适配器设置" (Adapter Settings, /adapter-management) or in config/adapter_policy.toml. To serve only specific groups, write:

toml
[[adapters]]
platform = "qq"            # platform only: applies to every account on it

[adapters.group]
default_action = "block"   # reject by default
allow_ids = ["test-group"] # only these groups are allowed

See Access Policy and Account Routing for all fields. Allow one test group and one test user first, then widen the scope once sending and receiving work.

Verify and Troubleshoot ​

Verify: after handing the prompt to an AI, its installation steps no longer mention the standalone NapCat / SnowLuma adapters; once you follow them, you can chat with Mai in the WebUI, and if QQ is connected, @-mentioning Mai in an allowed group (or messaging the official bot) gets a reply.

The AI still tells you to install NapCat Adapter / SnowLuma Adapter?

uv: command not found?

  • Run source $HOME/.local/bin/env to refresh the environment, or open a new terminal

"Model list cannot be empty" after startup?

  • Add at least one LLM model in the WebUI model configuration, save, and restart; see Model Configuration

The adapter cannot connect to the QQ client?

  • Check the [client] section of plugins/MaiBot-SnowLuma-Adapter/config.toml: server and port must match the client's forward WebSocket listener (default 127.0.0.1:3001), and token must match when authentication is enabled
  • Make sure the client is logged in with the forward WebSocket service enabled, and always start the client before MaiBot

No response when Mai is @-mentioned in a group?

  • First check whether the adapter policy allows that group: WebUI "Adapter Settings" or config/adapter_policy.toml—this is the first place to look when nothing happens
  • Then confirm bot.qq_account in config/bot_config.toml matches the QQ account logged in by the client exactly, and that the sender is not on the adapter's user blocklist