MaiBot (MaiSaka): an LLM agent built to feel like a person in QQ group chats

The problem MaiBot picks: group chat presence, not task completion

Most LLM chat bots are built around answering. You send a message, you get a structured reply, often with headings and bullet points. MaiBot's README states the opposite goal in its own words: the project wants a digital life form that is "more lifelike, not merely better", and the design notes say the original aim was to create a life form active in QQ group chats rather than a feature-complete bot. The README also argues that not everyone wants a perfect helpful assistant, and that some users want something that can make mistakes and has its own perceptions.

That framing decides the target user. MaiBot is for people who run a QQ group and want a participant that joins conversations at plausible moments, mimics the speaking style of the people around it, and picks up slang used inside that group. It is not aimed at teams that want an assistant to file tickets, answer support questions, or summarise documents. The README lists a plugin system with APIs and an event system as the extension path, so task-shaped behaviour is something you add, not something the core promises.

How the MaiCore architecture is laid out in the repository

The repository is a Python package with a clear split between the agent core and everything around it. pyproject.toml names the project MaiBot and describes it as "MaiCore 是一个基于大语言模型的可交互智能体", which is the core service. Top-level entries show the rest of the picture: bot.py as the entry point, src/ for the implementation, plugins/ for extensions, prompts/ for prompt material, dashboard/ for the web interface, locales/ plus crowdin.yml for translation, and pytests/ and tests/ for test code.

The dependency list in pyproject.toml tells you what the agent actually does at runtime. faiss-cpu and numpy and scipy point to vector similarity work, jieba and pypinyin and rapidfuzz and ahocorasick-rs point to Chinese text handling and keyword matching, sqlalchemy and sqlmodel point to a relational store, and openai plus google-genai point to model providers. maim-message is pinned at 0.6.8 and maibot-plugin-sdk at 2.8.1 or newer, so the message protocol and the plugin contract are versioned packages rather than in-tree code. mcp is constrained below version 2, which means the Model Context Protocol client is present but pinned to a major line. Playwright is a dependency and the Dockerfile installs Chromium system libraries, so some capability in the agent drives a browser; the README does not spell out which feature needs it.

The message path is not documented in the README beyond the adapter reference. The Dockerfile clones MaiBot-Napcat-Adapter into plugin-templates at build time, and the topics list qq-bot and qqbot, which places NapCat as the QQ-side transport. Everything between the adapter and the core runs over maim-message. If you want to know the exact event names or payload shapes, the README is silent and points at the documentation site instead.

Installing MaiBot with Docker Compose and reaching the WebUI

The README points at three install routes: the Release page for the latest version, a deployment guide at docs.mai-mai.org/manual/deployment/, and a Windows and macOS launcher called Maibot OneKey. The repository also ships a docker-compose.yml, which is the route shown here.

The compose file defines a single core service using the image sengokucola/maibot:latest, with infinitycat/maibot:latest listed as an alternative and dev tags commented out. It sets the timezone to Asia/Shanghai, points the statistics report at /MaiMBot/data/maibot_statistics.html, and sets WEBUI_HOST to 0.0.0.0 so the host can reach the WebUI through the port mapping. Two environment variables carry agreement hashes, EULA_AGREE and PRIVACY_AGREE, and a third, MAIBOT_LEGACY_0X_UPGRADE_CONFIRMED, skips an interactive migration prompt because Docker cannot answer it.

services:
  core:
    container_name: maim-bot-core
    image: sengokucola/maibot:latest
    environment:
      - TZ=Asia/Shanghai
      - EULA_AGREE=8e6e7d647f7f82d6ea98456b73908656
      - PRIVACY_AGREE=91e5db7659c560bc3545e63859b6ebc0
      - MAIBOT_LEGACY_0X_UPGRADE_CONFIRMED=1
      - WEBUI_HOST=0.0.0.0
    ports:
      - "18001:8001"
    restart: always

Start it with the standard Compose command from the repository root. The first run pulls the image, and because the compose file mounts ./docker-config/mmc to /MaiMBot/config, the bot configuration is generated or migrated into that host directory.

docker compose up -d
docker compose logs -f core

After the container reports ready, open http://localhost:18001 in a browser. That is the WebUI, mapped from container port 8001. The README does not document what the WebUI exposes beyond the screenshot in the repository, so treat the dashboard as the place to confirm the bot is alive rather than as a documented control surface.

The compose file also mounts ./data/MaiMBot/plugins, ./data/MaiMBot/emoji, ./data/MaiMBot/logs and ./depends-data, so plugin code, emoji assets, logs and runtime resources all survive a container rebuild. A commented Caddy block at the bottom shows the intended HTTPS path: drop the 18001 mapping, enable Caddy, and edit the Caddyfile according to dashboard/docs/Caddyfile.docker.example. If you would rather run from source, pyproject.toml requires Python 3.12 or newer and the repository uses uv with a lock file; the Dockerfile builds on python:3.13-slim and installs dependencies with uv sync --locked --no-dev.

Where MaiBot is the wrong tool

The clearest limitation is scope. The README frames the project around QQ group chat, and the Dockerfile bakes in the NapCat adapter. There is no Discord integration in the repository, and the related projects listed in the README go to Bilibili streaming and Minecraft rather than to another chat platform. If your community lives on Discord, MaiBot is not the agent to pick.

The second limitation is the definition of success. A bot tuned for lifelike behaviour is deliberately not tuned for accuracy or completeness. The README states that MaiSaka does not pursue perfection or efficiency above all else, and the design note says the goal is the most lifelike option rather than the best one. That is a real trade-off. If you need reliable, repeatable answers to user questions, an agent that imitates group slang and decides when to stay quiet will produce variable output, and the README offers no accuracy claim to offset that.

The third is operational. MaiBot needs a model provider, and the dependency list includes both openai and google-genai, so you supply credentials and pay for inference somewhere. The dependency set is large: faiss-cpu, numpy, scipy, pandas, pyarrow, playwright, sqlalchemy and a message protocol package all install before the bot starts. The Docker image avoids that on your host, but it also means the image is the unit you upgrade. The README does not document rollback, so a bad upgrade is recovered by pinning a different image tag yourself.

Finally, the README's install section still says "最新版本: v1.2.3" while pyproject.toml declares version 1.2.5 and the release list shows 1.2.4 dated 2026-09-01. Version references in the README lag the package metadata. Check the Release page rather than trusting the README's version line.

Alternatives: AstrBot, NoneBot and the fork path

AstrBot and NoneBot appear in the same search space as MaiBot, and both sit in the Python chat-bot ecosystem, but the split is about what the framework optimises. NoneBot is a general event-driven bot framework: you register handlers, match events, and write the reply logic yourself. It gives you a plugin and adapter architecture and leaves the conversational behaviour entirely to you. MaiBot ships an opinionated agent on top of its message protocol, with prompts, a plugin SDK, a dashboard and a personality model, so you get behaviour out of the box and give up the freedom to define it from scratch.

AstrBot is the closer comparison because it is also an LLM-oriented bot platform. The difference visible in this repository is the stated objective. MaiBot's README is explicit that the target is lifelike group presence rather than a helpful assistant, and that design principle drives the imitation of group members' speech and the decision about when not to reply. If you evaluate AstrBot, compare it on the same axis: whether the project's defaults aim at task completion or at social presence. The README does not compare MaiBot to either project, so any deeper feature comparison has to come from their own documentation.

The third option is the fork route. The README lists MoFox_Bot as an enhanced fork based on MaiCore 0.10.0. That matters for two reasons. It confirms the core is separable from the front end, and it means a fork can drift from the upstream protocol version, which is pinned here at maim-message 0.6.8. If you depend on plugin compatibility, check which core version a fork tracks before adopting it.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-09. Releases are frequent: 1.2.2 and 1.2.3 both landed on 2026-08-23, and 1.2.4 on 2026-09-01. pyproject.toml already declares 1.2.5. That cadence is the main upgrade cost. The README describes main as the stable branch and dev as the development branch carrying in-progress features, so you can choose the slower line, but the compose file defaults to the latest image tag rather than a pinned version. Pin the tag if you want upgrades to be a decision rather than a side effect of a restart.

The dependency pins matter when you upgrade. maim-message is pinned exactly at 0.6.8, json-repair is constrained below 0.61, mcp below 2, and the uv constraint list holds starlette below 1.4 along with minimum versions for cryptography, idna, pyjwt and urllib3. The plugin SDK is a lower bound at 2.8.1 or newer, so plugins built against a newer SDK may not run on an older core. The Dockerfile runs uv sync --locked, which means the lock file decides the resolved set, not the loose requirements.txt.

The licence is GPL-3.0. For anyone running MaiBot as a self-hosted group bot, the practical point is that GPL-3.0 is a copyleft licence: if you distribute a modified version, the source of your modifications has to be available under the same terms. Running it privately for your own group is a different situation from shipping a modified MaiBot to other people. The repository also carries EULA.md and PRIVACY.md at the top level, and the compose file will not start without the EULA_AGREE and PRIVACY_AGREE hashes, so those two documents are part of the deployment, not optional reading. This is a description of what the files say, not legal advice; read the licence and the EULA yourself before distributing anything.

Editorial conclusion

Adopt MaiBot if you run a QQ group and want an agent that reads the room and imitates how members speak, and you accept a GPL-3.0 codebase with a 250 MB plus Python dependency set. Do not adopt it if you need a task-completing assistant or a Discord bot: the repository ships a QQ adapter and a Bilibili streaming companion, not a Discord integration. Before committing, read EULA.md and PRIVACY.md, since docker-compose.yml requires the EULA_AGREE and PRIVACY_AGREE hashes to start, and confirm on the Release page which version you are pulling.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Mai-with-u/MaiBot on GitHub
3. Project website
4. README
5. Releases