MaiBot Documentation

GitHub

MaiSaka, an LLM-based intelligent agent, is a digital lifeform devoted to understanding you and interacting in the style of a real human.

5,690 stars

Python 1 file · ~1,917 tokens #agent #chat #chatbot #llm #llm-agent #llms #python #qq-bot

RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy MaiBot on any server, homelab, or cloud container platform.

Raw YAML Docker Page → JSON API

1-Click Terminal Command

bash (docker run)

docker run -d --name maibot -p 18001:18001 --restart always sengokucola/maibot:latest

Configured Services & Ports

⚙️ core

image: sengokucola/maibot:latest

🔌 Ports: 18001:8001

⚙️ napcat

image: mlikiowa/napcat-docker:latest

🔌 Ports: 6099:6099

⚙️ sqlite-web

image: coleifer/sqlite-web

🔌 Ports: 8120:8080

docker-compose.yml

yaml (docker-compose.yml)

services:
  core:
    container_name: maim-bot-core
    stop_grace_period: 70s # Runner 最多等待 Worker 60 秒，再保留强制退出时间
    #### prod ####
    image: sengokucola/maibot:latest
    # image: infinitycat/maibot:latest
    #### dev ####
    # image: sengokucola/maibot:dev
    # image: infinitycat/maibot:dev
    environment:
      - TZ=Asia/Shanghai
      - EULA_AGREE=8e6e7d647f7f82d6ea98456b73908656
      - PRIVACY_AGREE=91e5db7659c560bc3545e63859b6ebc0
      - MAIBOT_LEGACY_0X_UPGRADE_CONFIRMED=1 # Docker 无法交互确认旧版升级迁移，默认跳过确认提示
      - MAIBOT_STATISTICS_REPORT_PATH=/MaiMBot/data/maibot_statistics.html # 统计数据输出到共享目录，首次运行可自动创建文件
      - WEBUI_HOST=0.0.0.0 # Docker 中需要监听全部容器网卡，宿主机才能通过端口映射访问 WebUI
#      - EULA_AGREE=8e6e7d647f7f82d6ea98456b73908656 # 同意EULA
#      - PRIVACY_AGREE=91e5db7659c560bc3545e63859b6ebc0 # 同意隐私条款
    ports:
      - "18001:8001" # webui端口
#      - "8000:8000"
    volumes:
      # 监听地址和端口会用于生成或迁移 ./docker-config/mmc/bot_config.toml 的 maim_message 与 webui 配置段
      - ./docker-config/mmc:/MaiMBot/config # 持久化bot配置文件
      - ./data/MaiMBot:/MaiMBot/data # 共享目录
      - ./data/MaiMBot-plugin-data:/MaiMBot/data/plugins # 插件持久数据目录，与插件源码目录隔离
      - ./data/MaiMBot/emoji:/data/emoji # 持久化表情包
      - ./data/MaiMBot/plugins:/MaiMBot/plugins # 插件目录
      - ./data/MaiMBot/logs:/MaiMBot/logs # 日志目录
      - ./depends-data:/MaiMBot/depends-data # 运行时资源文件
      # - site-packages:/usr/local/lib/python3.13/site-packages # 持久化Python包，需要时启用
    restart: always
    networks:
      - maim_bot

  # 启用 HTTPS 时，建议注释掉 core 服务中的 "18001:8001" 端口映射，
  # 然后取消注释此 Caddy 反向代理示例块，并按 dashboard/docs/Caddyfile.docker.example 修改域名。
  # caddy:
  #   image: caddy:2
  #   container_name: maibot-caddy
  #   restart: always
  #   ports:
  #     - "80:80"
  #     - "443:443"
  #   volumes:
  #     - ./dashboard/docs/Caddyfile.docker.example:/etc/caddy/Caddyfile:ro
  #     - caddy_data:/data
  #     - caddy_config:/config
  #   depends_on:
  #     - core
  #   networks:
  #     - maim_bot
  napcat:
    environment:
      - NAPCAT_UID=1000
      - NAPCAT_GID=1000
      - TZ=Asia/Shanghai
    ports:
      - "6099:6099"
    volumes:
      - ./docker-config/napcat:/app/napcat/config # 持久化napcat配置文件
      - ./data/qq:/app/.config/QQ # 持久化QQ本体
      - ./data/MaiMBot:/MaiMBot/data # 共享目录
    container_name: maim-bot-napcat
    restart: always
    image: mlikiowa/napcat-docker:latest
    networks:
      - maim_bot
  sqlite-web:
    # 注意：coleifer/sqlite-web 镜像不支持arm64
    image: coleifer/sqlite-web
    container_name: sqlite-web
    restart: always
    ports:
      - "8120:8080"
    volumes:
      - ./data/MaiMBot:/data/MaiMBot
    environment:
      - SQLITE_DATABASE=MaiMBot/MaiBot.db  # 你的数据库文件
    networks:
      - maim_bot

  # chat2db占用相对较高但是功能强大
  # 内存占用约600m，内存充足推荐选此
  # chat2db:
  #   image: chat2db/chat2db:latest
  #   container_name: maim-bot-chat2db
  #   restart: always
  #   ports:
  #     - "10824:10824"
  #   volumes:
  #     - ./data/MaiMBot:/data/MaiMBot
  #   networks:
  #     - maim_bot
  
# volumes:         #  若需要持久化Python包时启用
#   site-packages:
#   caddy_data:
#   caddy_config:
networks:
  maim_bot:
    driver: bridge

1. Project Overview & Quickstart (Mai-with-u/MaiBot)

INTRO

麦麦 MaiSaka 是一个基于大语言模型的可交互智能体。

MaiSaka 不仅仅是一个机器人，不仅仅是一个可以帮你完成任务的“有帮助的助手”，她还是一个致力于了解你，并以真实人类的风格进行交互的数字生命。她不追求完美，不追求高效，但追求亲切和真实。
_{^{MaiSaka is an interactive agent based on large language models. MaiSaka is more than just a bot, and more than a "helpful assistant" that completes tasks. She is a digital life form that tries to understand you and interact in a genuinely human style. She does not pursue perfection or efficiency above all else. She pursues warmth and authenticity.}}

💭 没有人喜欢 GPT 的语言风格：麦麦使用了更加自然、贴合人类对话习惯的交互方式，不是长篇大论或者 markdown 格式的分点，而是或长或短的闲谈。
_{^{No one likes GPT-sounding dialogue: MaiSaka uses a more natural conversational style. Instead of long-winded markdown-heavy replies, she chats in a way that feels casual, varied, and human.}}
🎭 不再是傻乎乎的一问一答：懂得在合适的时间说话，把握聊天中的气氛，在合适的时候开口，在合适的时候闭嘴。
_{^{No longer stuck in rigid Q&A: She knows when to speak, how to read the room, when to join a conversation, and when to stay quiet.}}
🧠 麦麦·成为人类：在多人对话中，麦麦会模仿其他人的说话风格，还会自主理解新词或者小圈子里的黑话，不断进化。
_{^{MaiSaka becoming human: In group conversations, MaiSaka imitates how people around her speak, learns new slang and in-group language, and keeps evolving.}}
❤️ 永远都在更加了解你：基于心理学中人格理论，麦麦会不断积累对于你的了解，不论是你的信息、喜恶或是行为风格，她都记在心里。
_{^{Always learning more about you: Inspired by personality theory in psychology, MaiSaka gradually builds an understanding of your preferences, traits, habits, and behavior style.}}
🔌 插件系统：提供强大的 API 和事件系统，拥有无限扩展可能。
_{^{Plugin system: Provides powerful APIs and an event system with virtually unlimited room for extension.}}

安装 · INSTALL

最新版本: v1.2.1

_{^{Latest Version: v1.2.1}}

发布：Release 页面展示了最新发布的正式版。
_{^{Download: Visit the Release page to get the latest version.}}
部署教程

_{^{Deployment Guide}}

方便使用的麦麦启动器下载 (Windows/MAC)：Maibot-OK
_{^{Launcher: Maibot OneKey}}

分支 / Branch
`main`	稳定版 · STABLE
`dev`	开发版，包含开发中的新功能 · DEV

📚 文档 · DOC

📚 麦麦文档：最全面的文档中心，了解麦麦的一切。
_{^{📚 Documentation: The most comprehensive documentation hub for everything about MaiSaka.}}
[演示视频]

前往麦麦演示视频 / Watch the MaiSaka video

💬 讨论与社区 · Discussion/Community

群组 / Group	说明 / Description
麦麦脑电图:571780722_{^{MaiBrain EEG}}	技术交流 / 答疑_{^{Technical discussion / Q&A}}
麦麦大脑磁共振:766798517_{^{MaiBrain MRI}}	技术交流 / 答疑_{^{Technical discussion / Q&A}}
麦麦要当 VTB_{^{Mai Wants to Be a VTuber}}	技术交流 / 答疑_{^{Technical discussion / Q&A}}
麦麦闲聊群_{^{Mai Casual Chat Group}}	以闲聊为主_{^{Casual chat only, no support}}
插件开发群:1036092828_{^{Plugin Dev Group}}	插件、进阶开发与测试_{^{Advanced development and testing}}

Amaidesu：让麦麦在 B 站开播。
_{^{Let MaiSaka stream on Bilibili.}}
MoFox_Bot：基于 MaiCore 0.10.0 的 Fork。
_{^{An enhanced fork based on MaiCore 0.10.0.}}
MaiCraft：让麦麦陪你玩 Minecraft（暂时停止维护中）。
_{^{Let MaiSaka accompany you in Minecraft (currently paused).}}

💡 设计理念 · IDEA

千石可乐说：
_{^SengokuCola:}

这个项目最初只是为了给牛牛 bot 添加一点额外的功能，但是功能越写越多，最后决定重写。其目的是为了创造一个活跃在 QQ 群聊的“生命体”。目的并不是为了写一个功能齐全的机器人，而是一个尽可能让人感知到真实的类人存在。
_{^{This project originally started as a few extra features for the NiuNiu bot, but it kept growing until a full rewrite became inevitable. The goal was to create a "life form" active in QQ group chats, not a feature-complete bot, but something as human-like and real-feeling as possible.}}

程序的功能设计理念基于一个核心的原则：“最像而不是好”。
_{^{The core design principle is: "more lifelike, not merely better."}}

如果人类真的需要一个 AI 来陪伴自己，并不是所有人都需要一个完美的，能解决所有问题的“helpful assistant”，而是一个会犯错的，拥有自己感知和想法的“生命形式”。
_{^{If people truly want AI companionship, not everyone needs a perfect "helpful assistant" that solves every problem. Some people may want a life form that can make mistakes and has its own perceptions and thoughts.}}

🌟 贡献和致谢 · Contributors

欢迎参与贡献！请先阅读贡献指南。
_{^{Contributions are welcome. Please read the Contribution Guide first.}}

🌟 贡献者

_{^Contributors}

🤝 开源项目友链

_{^{Open Source Friends}}

AstrBot: 优秀的LLM Agent项目
_{^{An excellent LLM Agent project.}}

❤️ 特别致谢

_{^{Special Thanks}}

萨卡班甲鱼：千石可乐很喜欢的生物。
_{^{Sacabambaspis: SengokuCola's favorite creature.}}
略nd：为麦麦绘制早期的精美人设。
_{^{Drew MaiSaka's beautiful early character design.}}
NapCat：现代化的基于 NTQQ 的 Bot 协议实现。
_{^{A modern NTQQ-based bot protocol implementation.}}

📊 仓库状态

_{^{Repository Status}}

Star History

📌 注意事项 & License

_{^{Notice & License}}

[!IMPORTANT]
使用前请阅读用户协议 (EULA) 和隐私协议。AI 生成内容请仔细甄别。
_{^{Please read the End User License Agreement (EULA) and Privacy Policy before use. Please evaluate AI-generated content carefully.}}

License: GPL-3.0

2. Official Technical Reference & Guides (Mai-with-u/docs)

MaiBot 文档

本仓库为 MaiBot 的官方文档。MaiBot 是一个智能聊天机器人，专为 QQ 群设计，具有基于 LLM 的对话能力、记忆系统和情感表达功能。

关于文档

此文档站点使用 VitePress 构建，涵盖了安装、部署、配置以及开发（未完成） MaiBot 所需的所有内容。

文档部分

文档目录

安装指南
提供标准版和新手友好版的安装步骤，帮助用户快速上手。
API 参考（未完成）
详细介绍 MaiBot 提供的 API 接口及其使用方法。
部署方法
涵盖多种部署方式，包括 Docker、Linux、Windows 和群晖 NAS。
常见问题解答和故障排除
收录常见问题及其解决方案，帮助用户排查和解决问题。
文件结构和配置
说明项目的文件结构及配置方法，便于用户自定义和扩展。

本地开发

本地部署要求

使用Nodejs安装对应依赖

bash

# 安装依赖
pnpm install

# 启动开发服务器
pnpm docs:dev

# 构建生产版本
pnpm docs:build

# 预览生产版本
pnpm docs:preview

贡献

完整方式

如果你想要修改文档，首先fork在修改后提出PR即可。

如果你想要添加文件，在fork后添加你写的文档并放入对应目录（或者新建目录），修改各级的index.md使其包含您的文档。

然后找到.vitepress下的config.mts文件，修改其中的导航使其能正确导航到你的文件。

随后发起PR即可

懒人方式

如果你想要修改文档，首先fork在修改后提出PR即可。

如果你想要添加文件，在fork后添加你写的文档并放入根目录，随后发起PR，说明你想放置的目录位置。

若PR通过，我们会手动帮你配置各类目录

Docker & Self-Hosted Deployment Verified OCI

1. Project Overview & Quickstart (Mai-with-u/MaiBot) Copy Chapter

INTRO Copy Chapter

安装 · INSTALL Copy Chapter

📚 文档 · DOC Copy Chapter

💬 讨论与社区 · Discussion/Community Copy Chapter

🧩 衍生项目 · Related Projects Copy Chapter

💡 设计理念 · IDEA Copy Chapter

🌟 贡献和致谢 · Contributors Copy Chapter

🌟 贡献者 Copy Section

🤝 开源项目友链 Copy Section

❤️ 特别致谢 Copy Section

📊 仓库状态 Copy Chapter

Star History Copy Section

📌 注意事项 & License Copy Chapter

2. Official Technical Reference & Guides (Mai-with-u/docs) Copy Chapter

MaiBot 文档

关于文档 Copy Chapter

文档部分 Copy Chapter

文档目录 Copy Section

本地开发 Copy Chapter

本地部署要求 Copy Section

贡献 Copy Chapter

完整方式 Copy Section

懒人方式 Copy Section

Explore Related Technologies & Topics