MaiBot全流程配置与工作原理

发表于 更新于 分类于 本文字数： 1.2k 阅读时长 ≈ 4 分钟
MaiBot,一个多模型，拟人化，可拓展的智能体

一 . 概述

MaiBot 是一个高度整合的 AI 机器人系统，它本体负责：

  • LLM 回复
  • 人格设定
  • 记忆系统
  • 插件机制

但它 不能直接连接 QQ。
所以需要 Napcat 来作为 QQ 的协议层（负责登录 QQ、接收 QQ 消息、发消息）。
Napcat 不能直接连 MaiBot，于是有 Adapter（适配器） 充当桥接角色。

二 . 系统架构 (核心组件之间的关系)

1
2
3
4
5
6
NapcatQQ（连接 QQ）
   ↓ WebSocket 推送事件
MaiBot-Napcat-Adapter（做协议翻译）
   ↓ WebSocket 内部通信
MaiBot（机器人本体）

各自负责 :

组件 作用
NapcatQQ 负责登录QQ, 接收QQ消息,发消息
Adapter Napcat格式 <—-> MaiBot格式之间的转换桥梁
MaiBot 负责人格, 模型, 记忆, 插件, 最终回复

三 . 整体通信链路

完整链路如下:

  1. QQ接收消息
  2. NapcatQQ监听qq, 收到事件
  3. NapcatQQ将事件通过反向WebSocket (ws)推给Adapter(端口8095)
  4. Adapter解析事件,转发给MaiBot(端口8000)
  5. MaiBot调用模型生成回复
  6. MaiBot通过ws返回消息给Adapter
  7. Adapter通过NapcatQQ发回给QQ

关键端口说明:

端口 组件 用途 是否对外网开放
8000 MaiBot MaiBot的WebSocket服务器,专门用来给Adapter连接用 no
8001 MaiBot WebUI MaiBot的配置界面 yes
8095 Adapter Napcat反向WS的输入口 no
6099 Napcat WebUI Napcat的配置界面 yes

四 . 一键部署教程(linux)

1. MaiBot + Napcat-Adapter

参考官方文档 :

(MaiBot Linux 一键脚本部署 | MaiBot 文档中心 (mai-mai.org))

关键脚本:

1
2
wget -O maibot-install.sh https://raw.githubusercontent.com/Astriora/Antlia/refs/heads/main/Script/MaiBot/MaiBot-install.sh &&
bash maibot-install.sh

说明:一键部署之后推荐再看一下linux手动部署的步骤,以便知道这个一键部署都干了什么事

这个脚本主要做了:

  1. 拉取MaiBot主程序和Adapter主程序
  2. 创建虚拟环境
  3. 安装依赖
  4. 创建sreen运行对话(挂在后台不断线运行)
  5. 生成Web UI(8001)
  6. 生成.env/配置文件
  7. 提示使用maibot命令进行控制

这个一键脚本不仅部署了MaiBot,还顺便部署了Adapter和screen会话

2. Napcat

参考官方文档:

选择 NapCat.Installer - Linux 一键使用脚本

1
2
3
4
curl -o \
napcat.sh \
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh \
&& bash napcat.sh
  • 下载完成之后输入命令
1
napcat

按照提示输入qq号并且扫码登录

两种配置Websocket客户端方法任选其一

使用终端交互配置界面

打开选项4

名称任意,token任意(注意13位以上) , url填写ws://localhost:8095(Adapter的默认端口),保存即可.

使用WebUI 配置

启用Web UI配置,默认端口6099, 在浏览器直接打开即可,在[网络配置] 里面[新建] [Websocket客户端]

信息填写与终端交互配置界面一致

  • 保存之后启动napcat服务

3. 配置Adapter

路径

1
~/MaiBot-Napcat-Adapter/config.toml

关键部分:

  • 确认一下端口是不是8095
  • 设置一下黑白名单, 简单方法,把初始设置的whitelist改成blacklist, group_list和private_list都留空,方便前期测试,后续根据个人需求更改,配置完保存退出
1
2
3
4
5
6
7
8
9
10
[chat] # 黑白名单功能
group_list_type = "blacklist" # 群组名单类型，可选为：whitelist, blacklist
group_list = []               # 群组名单
# 当group_list_type为whitelist时，只有群组名单中的群组可以聊天
# 当group_list_type为blacklist时，群组名单中的任何群组无法聊天
private_list_type = "blacklist" # 私聊名单类型，可选为：whitelist, blacklist
private_list = []               # 私聊名单
# 当private_list_type为whitelist时，只有私聊名单中的用户可以聊天
# 当private_list_type为blacklist时，私聊名单中的任何用户无法聊天

4 . 启动服务

输入

1
maibot

弹出菜单

按1 启动所有服务(后台启动)

说明 : 5, 6 分别是MaiBot 和Adapter的日志, 打开日志之后想关掉不要直接按ctrl + c,会直接停掉服务,按ctrl + A D 即可

5. 配置api-key

注册一个硅基流动 , 可以使用别人的邀请码,这样双方都能免费得到14块钱的token,(本人邀请码是WwUwVurs, 填填我的把,欧内该😢😢), 把创建好的api密钥保存下来

访问8001端口打开Maibot Web UI

在[麦麦模型提供商配置]中填入刚刚的api-key (注意选择硅基流动)

重启麦麦一下就可以正式开始使用了, 在qq里面给bot发消息,再看看日志正不正常😋😋

五. 后记

  • 本人一开始部署的时候不清楚项目架构, 不知道napcat需要独立安装, 以为napcat-adapter就能直接连接qq,卡了很长时间, 🍬得要死.
  • 总体不是很复杂,感谢看到这里…..