MaiBot 部署笔记

先看两个逗逼的：
![](https://wkphoto.bj.bcebos.com/023b5bb5c9ea15ce9bc34e55a6003af33a87b2b9.jpg)
![](https://wkphoto.bj.bcebos.com/3b87e950352ac65ca528c82febf2b21193138ab9.jpg)

我群里的逆女跑了两个多星期，中间搬了两次家，OOM 了好几次，踩了不少坑。这篇把完整的搭建流程和踩过的坑整理一下，给想自己养一只麦麦的人参考。

> 官方文档：<https://docs.mai-mai.org>。Windows 用户可以直接用官方的一键启动器，本文写的是 **Linux 服务器长期运行**的做法。版本以 MaiBot 1.3.x 为准。

## 一、先搞懂它是怎么跑起来的

一只能在 QQ 群说话的麦麦，由三部分组成：

```
QQ 群  ⇄  NapCat（登录一个 QQ 号）  ⇄  MaiBot（大脑）  ⇄  大模型 API
                    WebSocket                     HTTP
```

- **NapCat**：一个无界面 QQ 客户端，帮你登录机器人 QQ 号，再通过 OneBot 协议把消息转给别的程序。
- **MaiBot**：真正的「大脑」，负责看消息、决定要不要说话、调模型、管记忆。
- **大模型 API**：麦麦本身不带模型，要你提供 OpenAI 兼容的接口和 Key。

NapCat 和 MaiBot 可以装在同一台机器上，也可以分开装。我是分开的，NapCat 一台，麦麦一台。

## 二、准备

| 项目 | 建议 |
| --- | --- |
| 服务器 | **至少 2 核 4G**。别信「2G 够用」，下面会讲 |
| 系统 | Debian / Ubuntu / 任何有 systemd 的发行版 |
| Python | 3.12 以上，我用的是 3.13 |
| QQ 号 | 一个小号，**别用主号**，有被风控的风险 |
| 模型 API | 至少一家 OpenAI 兼容接口的 Key |

### 关于内存

我一开始把麦麦放在一台 2G 的小机器上：启动 1 分钟涨到 800M，4 分钟到 1.2G。开了长期记忆、装了一堆插件以后，一晚上 OOM 两次，整台机器卡死，连 SSH 都进不去。后来搬到 4G 的机器上，才安稳下来。

**麦麦常驻大概要 1.2~1.5G，最好给它留 2G 的余量。**

## 三、装 NapCat

NapCat 的安装看它自己的文档（<https://napneko.github.io>），官方有一键脚本。装好以后要做三件事：

1. 用手机 QQ 扫码登录机器人号。
2. 打开 NapCat 的 WebUI，进「网络配置」，**新建一个 WebSocket 服务端**：
   - 端口随便定，比如 `3001`；
   - **一定要设 Token**，否则谁连上来都能用你的 QQ 号发消息。
3. 如果 NapCat 和麦麦不在同一台机器上，记得在防火墙或安全组里放行这个端口，**最好只放行麦麦那台机器的 IP**。

> ⚠️ 踩坑：NapCat 没有守护进程时，机器一重启、或者在 WebUI 里点了更新，它就不会再起来。建议用 systemd 或者 screen 守着它。掉登录后要重新扫码，二维码在日志里。

## 四、装 MaiBot

### 1. 建个专用用户

别用 root 跑：

```bash
useradd -r -m -d /opt/maibot -s /bin/bash maibot
```

### 2. 下载源码

从 GitHub Releases（<https://github.com/Mai-with-u/MaiBot/releases>）下载最新版，解压到 `/opt/maibot/core`。

### 3. 装 Python 环境

推荐用 `uv`，装 Python 和装依赖都快得多：

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
cd /opt/maibot
uv venv --python 3.13 venv
uv pip install --python venv/bin/python -r core/requirements.txt
chown -R maibot:maibot /opt/maibot
```

国内服务器可以加 `--index-url https://mirrors.cloud.tencent.com/pypi/simple` 换镜像。

### 4. 第一次在前台跑

```bash
sudo -u maibot -i
cd /opt/maibot/core
../venv/bin/python bot.py
```

第一次启动会让你同意用户协议和隐私条款，同意之后会在 `config/` 下生成配置文件。看到它正常启动就可以 `Ctrl+C` 先停掉，去改配置。

## 五、配置

麦麦的配置主要是两个文件，都在 `core/config/` 下面：

- `model_config.toml`：模型提供商、模型列表、各项任务用哪些模型；
- `bot_config.toml`：人设、聊天行为、记忆、WebUI 等。

**更省事的办法是开 WebUI**（默认端口 `8001`），基本所有配置都能在网页上点。改完大部分配置会**热重载**，不用重启。

### 1. 配模型

在 `model_config.toml` 里先加提供商：

```toml
[[api_providers]]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
api_key = "sk-你的key"
client_type = "openai"
```

再加模型：

```toml
[[models]]
model_identifier = "deepseek-chat"   # 接口里真实的模型名
name = "ds-flash"                     # 你自己起的名字，下面引用它
api_provider = "DeepSeek"
```

最后给各个「任务」分配模型。最重要的是这几个：

| 任务 | 干什么 | 选什么样的模型 |
| --- | --- | --- |
| `replyer` | 生成回复 | **说话最像人的**。决定麦麦的「性格表现」 |
| `planner` | 决定说不说话、要不要用工具 | **快、会调工具**的。不要开思考 |
| `utils` | 总结、整理之类的杂活 | 便宜、快 |
| `vlm` | 看图 | 支持图片的模型 |
| `embedding` | 记忆检索用的向量 | 比如 `bge-m3` |

```toml
[model_task_config.replyer]
model_list = ["ds-flash"]
```

一个任务可以填多个模型，麦麦会在它们之间做负载均衡，某个挂了会自动换下一个。**强烈建议每个任务都配两家以上**，免费或便宜的接口经常抽风。

我的经验：

- **planner 千万别用开思考的模型**，一次规划要等十几秒，群里早聊到别的话题了；
- **replyer 用人设去测**：问「你是不是 AI」「你是什么模型」，会直接说「我是 Claude」的模型不适合当回复模型；
- 有些中转站会偷偷注入自己的系统提示词，导致人设掉马，测一下再上。

### 2. 配人设

在 WebUI 的「人格」里写就行。写得具体比写得长更有用，比如：

> 大二女大学生，BanG Dream 老粉，说话随意，不用 emoji，偶尔用颜文字，不会主动说自己是 AI。

### 3. 接上 NapCat

麦麦通过 NapCat 适配器插件（`plugins/napcat_adapter`）连 NapCat。编辑它的 `config.toml`：

```toml
[napcat_server]
host = "NapCat 所在机器的 IP"
port = 3001
# token 填你在 NapCat 里设的那个

[chat]
group_list_type = "blacklist"   # 黑名单模式：除了列表里的群，都说话
group_list = []
private_list_type = "whitelist" # 白名单模式：私聊只回列表里的人
private_list = []
ban_qq_bot = true
```

如果这个 QQ 号同时还挂着别的机器人（比如签到机器人），可以在 `bot_config.toml` 里配**正则黑名单**，把「签到」「帮助」这类指令过滤掉，免得麦麦抢答。

## 六、用 systemd 让它常驻

新建 `/etc/systemd/system/maibot.service`：

```ini
[Unit]
Description=MaiBot
After=network-online.target

[Service]
User=maibot
WorkingDirectory=/opt/maibot/core
Environment=PYTHONUNBUFFERED=1 TZ=Asia/Shanghai
ExecStart=/opt/maibot/venv/bin/python bot.py
Restart=always
RestartSec=10
Nice=10
MemoryMax=2000M
MemorySwapMax=512M
CPUQuota=80%

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload
systemctl enable --now maibot
journalctl -u maibot -f     # 看日志
```

关于内存限制的几个坑，都是我真踩过的：

- **只设 `MemoryMax`、不设 `MemorySwapMax` 是不够的**：内存泄漏会全溢出到 swap，机器 IO 跑满、全卡死，就是不触发 OOM。一定要给 swap 也设上限。
- **不要设 `MemoryHigh`**：它会把页缓存也算进去持续回收，我设过一次，结果 85% 的 iowait，WebUI 直接卡死。
- **用 `systemctl set-property` 改的限制，重启机器就没了**。要写成 `/etc/systemd/system/maibot.service.d/xxx.conf` 这样的 drop-in 文件。
- 加上 `Restart=always`，就算 OOM 被杀了，它也会自己起来。

## 七、玩出花样

跑稳了以后，可以慢慢加东西：

- **插件**：WebUI 里有插件市场，戳一戳、复读、B 站视频理解、群聊总结、海龟汤之类的都有。装完插件要重启麦麦。
- **长期记忆**：在 `bot_config.toml` 里开 A_Memorix，麦麦会自己记住群里发生的事。也可以手动把知识「喂」给她：把 txt 放进 `data/a-memorix/imports/source/raw/`，再用 `src/A_memorix/scripts/process_knowledge.py` 导入。我给她喂过一份「酒馆常见问题」，还有一次「造反被群主抽皮鞭」的黑历史，她现在一提起就委屈。
- **自己写插件**：麦麦的插件 SDK 不难，我写过联网搜索、一日情缘，还有一台给她自己用的沙箱电脑。

## 八、几个小建议

1. **把 `core/` 用 git 管起来。** 改了源码或插件就 commit 一下。升级或者改坏了，回滚就是一条命令的事。记得把含 Key 的 `config/*.toml` 和 `data/` 排除在外。
2. **改配置之前先备份**，WebUI 里手一滑就能删掉整个提供商（别问我怎么知道的）。
3. **WebUI 如果要开公网，一定要设强口令**，最好只监听本机，用 SSH 隧道访问。
4. **日志会越攒越多**，写个 cron 定期清，不然哪天磁盘就满了。
5. **别同时开两个实例连同一个 NapCat**，否则一条消息会回两遍。

---

阿巴阿巴，本文章部分资料参考maibot官方文档，且文章润色过。

先看两个逗逼的：

官方文档：https://docs.mai-mai.org。Windows 用户可以直接用官方的一键启动器，本文写的是 Linux 服务器长期运行的做法。版本以 MaiBot 1.3.x 为准。

一、先搞懂它是怎么跑起来的

一只能在 QQ 群说话的麦麦，由三部分组成：

QQ 群  ⇄  NapCat（登录一个 QQ 号）  ⇄  MaiBot（大脑）  ⇄  大模型 API
                    WebSocket                     HTTP

NapCat：一个无界面 QQ 客户端，帮你登录机器人 QQ 号，再通过 OneBot 协议把消息转给别的程序。
MaiBot：真正的「大脑」，负责看消息、决定要不要说话、调模型、管记忆。
大模型 API：麦麦本身不带模型，要你提供 OpenAI 兼容的接口和 Key。

NapCat 和 MaiBot 可以装在同一台机器上，也可以分开装。我是分开的，NapCat 一台，麦麦一台。

二、准备

项目	建议
服务器	至少 2 核 4G。别信「2G 够用」，下面会讲
系统	Debian / Ubuntu / 任何有 systemd 的发行版
Python	3.12 以上，我用的是 3.13
QQ 号	一个小号，别用主号，有被风控的风险
模型 API	至少一家 OpenAI 兼容接口的 Key

关于内存

麦麦常驻大概要 1.2~1.5G，最好给它留 2G 的余量。

三、装 NapCat

NapCat 的安装看它自己的文档（https://napneko.github.io），官方有一键脚本。装好以后要做三件事：

用手机 QQ 扫码登录机器人号。
打开 NapCat 的 WebUI，进「网络配置」，新建一个 WebSocket 服务端：
- 端口随便定，比如 3001；
- 一定要设 Token，否则谁连上来都能用你的 QQ 号发消息。
如果 NapCat 和麦麦不在同一台机器上，记得在防火墙或安全组里放行这个端口，最好只放行麦麦那台机器的 IP。

⚠️ 踩坑：NapCat 没有守护进程时，机器一重启、或者在 WebUI 里点了更新，它就不会再起来。建议用 systemd 或者 screen 守着它。掉登录后要重新扫码，二维码在日志里。

四、装 MaiBot

1. 建个专用用户

别用 root 跑：

useradd -r -m -d /opt/maibot -s /bin/bash maibot

2. 下载源码

从 GitHub Releases（https://github.com/Mai-with-u/MaiBot/releases）下载最新版，解压到 /opt/maibot/core。

3. 装 Python 环境

推荐用 uv，装 Python 和装依赖都快得多：

curl -LsSf https://astral.sh/uv/install.sh | sh
cd /opt/maibot
uv venv --python 3.13 venv
uv pip install --python venv/bin/python -r core/requirements.txt
chown -R maibot:maibot /opt/maibot

国内服务器可以加 --index-url https://mirrors.cloud.tencent.com/pypi/simple 换镜像。

4. 第一次在前台跑

sudo -u maibot -i
cd /opt/maibot/core
../venv/bin/python bot.py

第一次启动会让你同意用户协议和隐私条款，同意之后会在 config/ 下生成配置文件。看到它正常启动就可以 Ctrl+C 先停掉，去改配置。

五、配置

麦麦的配置主要是两个文件，都在 core/config/ 下面：

model_config.toml：模型提供商、模型列表、各项任务用哪些模型；
bot_config.toml：人设、聊天行为、记忆、WebUI 等。

更省事的办法是开 WebUI（默认端口 8001），基本所有配置都能在网页上点。改完大部分配置会热重载，不用重启。

1. 配模型

在 model_config.toml 里先加提供商：

[[api_providers]]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
api_key = "sk-你的key"
client_type = "openai"

再加模型：

[[models]]
model_identifier = "deepseek-chat"   # 接口里真实的模型名
name = "ds-flash"                     # 你自己起的名字，下面引用它
api_provider = "DeepSeek"

最后给各个「任务」分配模型。最重要的是这几个：

任务	干什么	选什么样的模型
`replyer`	生成回复	说话最像人的。决定麦麦的「性格表现」
`planner`	决定说不说话、要不要用工具	快、会调工具的。不要开思考
`utils`	总结、整理之类的杂活	便宜、快
`vlm`	看图	支持图片的模型
`embedding`	记忆检索用的向量	比如 `bge-m3`

[model_task_config.replyer]
model_list = ["ds-flash"]

一个任务可以填多个模型，麦麦会在它们之间做负载均衡，某个挂了会自动换下一个。强烈建议每个任务都配两家以上，免费或便宜的接口经常抽风。

我的经验：

planner 千万别用开思考的模型，一次规划要等十几秒，群里早聊到别的话题了；
replyer 用人设去测：问「你是不是 AI」「你是什么模型」，会直接说「我是 Claude」的模型不适合当回复模型；
有些中转站会偷偷注入自己的系统提示词，导致人设掉马，测一下再上。

2. 配人设

在 WebUI 的「人格」里写就行。写得具体比写得长更有用，比如：

大二女大学生，BanG Dream 老粉，说话随意，不用 emoji，偶尔用颜文字，不会主动说自己是 AI。

3. 接上 NapCat

麦麦通过 NapCat 适配器插件（plugins/napcat_adapter）连 NapCat。编辑它的 config.toml：

[napcat_server]
host = "NapCat 所在机器的 IP"
port = 3001
# token 填你在 NapCat 里设的那个

[chat]
group_list_type = "blacklist"   # 黑名单模式：除了列表里的群，都说话
group_list = []
private_list_type = "whitelist" # 白名单模式：私聊只回列表里的人
private_list = []
ban_qq_bot = true

如果这个 QQ 号同时还挂着别的机器人（比如签到机器人），可以在 bot_config.toml 里配正则黑名单，把「签到」「帮助」这类指令过滤掉，免得麦麦抢答。

六、用 systemd 让它常驻

新建 /etc/systemd/system/maibot.service：

[Unit]
Description=MaiBot
After=network-online.target

[Service]
User=maibot
WorkingDirectory=/opt/maibot/core
Environment=PYTHONUNBUFFERED=1 TZ=Asia/Shanghai
ExecStart=/opt/maibot/venv/bin/python bot.py
Restart=always
RestartSec=10
Nice=10
MemoryMax=2000M
MemorySwapMax=512M
CPUQuota=80%

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now maibot
journalctl -u maibot -f     # 看日志

关于内存限制的几个坑，都是我真踩过的：

只设 MemoryMax、不设 MemorySwapMax 是不够的：内存泄漏会全溢出到 swap，机器 IO 跑满、全卡死，就是不触发 OOM。一定要给 swap 也设上限。
不要设 MemoryHigh：它会把页缓存也算进去持续回收，我设过一次，结果 85% 的 iowait，WebUI 直接卡死。
用 systemctl set-property 改的限制，重启机器就没了。要写成 /etc/systemd/system/maibot.service.d/xxx.conf 这样的 drop-in 文件。
加上 Restart=always，就算 OOM 被杀了，它也会自己起来。

七、玩出花样

跑稳了以后，可以慢慢加东西：

插件：WebUI 里有插件市场，戳一戳、复读、B 站视频理解、群聊总结、海龟汤之类的都有。装完插件要重启麦麦。
长期记忆：在 bot_config.toml 里开 A_Memorix，麦麦会自己记住群里发生的事。也可以手动把知识「喂」给她：把 txt 放进 data/a-memorix/imports/source/raw/，再用 src/A_memorix/scripts/process_knowledge.py 导入。我给她喂过一份「酒馆常见问题」，还有一次「造反被群主抽皮鞭」的黑历史，她现在一提起就委屈。
自己写插件：麦麦的插件 SDK 不难，我写过联网搜索、一日情缘，还有一台给她自己用的沙箱电脑。

八、几个小建议

把 core/ 用 git 管起来。 改了源码或插件就 commit 一下。升级或者改坏了，回滚就是一条命令的事。记得把含 Key 的 config/*.toml 和 data/ 排除在外。
改配置之前先备份，WebUI 里手一滑就能删掉整个提供商（别问我怎么知道的）。
WebUI 如果要开公网，一定要设强口令，最好只监听本机，用 SSH 隧道访问。
日志会越攒越多，写个 cron 定期清，不然哪天磁盘就满了。
别同时开两个实例连同一个 NapCat，否则一条消息会回两遍。

阿巴阿巴，本文章部分资料参考maibot官方文档，且文章润色过。

Last modification：October 27, 2026

MaiBot 部署笔记

一、先搞懂它是怎么跑起来的

二、准备

关于内存

三、装 NapCat

四、装 MaiBot

1. 建个专用用户

2. 下载源码

3. 装 Python 环境

4. 第一次在前台跑

五、配置

1. 配模型

2. 配人设

3. 接上 NapCat

六、用 systemd 让它常驻

七、玩出花样

八、几个小建议

MaiBot 部署笔记

嗯对就是我又又又换博客了

之前的垃圾玩意...

欢迎使用 Typecho

我做了一个OC工具

欢迎使用 Typecho

自己写自动备份留下的坑

嗯对就是我又又又换博客了

之前的垃圾玩意...

MaiBot 部署笔记

MaiBot 部署笔记

小吕

一、先搞懂它是怎么跑起来的

二、准备

关于内存

三、装 NapCat

四、装 MaiBot

1. 建个专用用户

2. 下载源码

3. 装 Python 环境

4. 第一次在前台跑

五、配置

1. 配模型

2. 配人设

3. 接上 NapCat

六、用 systemd 让它常驻

七、玩出花样

八、几个小建议

MaiBot 部署笔记