MaiBot 文档中心

简体中文

English

简体中文

English

外观

安装插件 ​

更新: 2026/10/20字数: 2022 字时长: 7 分钟

插件就像给 MaiBot 安装的「App」，让它拥有更多能力——游戏、画图、音乐、天气查询，以及把 QQ、邮件、语音通话等平台接入麦麦的适配器，几乎都以插件形式存在。

从内置的插件市场或 Git 仓库安装插件。开发插件请阅读插件接入和插件开发文档。

什么是插件 ​

  • 🎮 功能型插件 — 游戏、画图、音乐、天气等
  • 🔌 平台适配器 — 把消息平台接进 MaiBot，它们本身也是插件
  • 🛠️ 开发向组件 — Tool、Command、Hook、事件处理器等

插件市场（推荐） ​

MaiBot 内置插件市场（Plugin Market），在 WebUI 里就能浏览、安装、更新插件，无需命令行。

插件市场

市场支持按分类、关键词和作者筛选，快速定位你需要的插件或适配器：

插件市场筛选与分类

工具栏上的「仅显示当前版本」开关决定是否隐藏与当前麦麦版本不兼容的插件；关掉它可以顺手看看有哪些插件升级了麦麦才能用。插件卡片上的「不兼容」提示会说明原因，版本详情见下一节。

从插件市场安装 ​

在「插件扩展 → 插件市场 / 浏览」中找到插件并安装：

  • 已发布 Release 且收录于官方版本索引的插件，选择发布版本安装
  • 仅维护分支的插件，选择分支安装
  • 安装后默认禁用，需在管理插件中启用

市场里找不到？

插件市场的索引来自插件仓库，信息源可在市场设置里切换为麦麦官方、CNB 或 GitHub。如果搜不到，也可以用下面的 Git 地址方式安装任意公开仓库。

选择要安装的版本 ​

官方版本索引会为每个已收录插件维护一份发布版本列表（来自仓库的 Git Release），你可以在插件详情页的「安装版本」卡片里指定装哪一个。

版本下拉里每一行的后缀就是它的状态：

  • · 推荐 — 当前麦麦与 SDK 都兼容、且不是预发布的最新稳定版，默认选中
  • · 预发布 — 作者标记的 prerelease，可能有未稳定的改动
  • · 已撤回 — 作者已撤回该版本，装它会失败
  • · 不兼容原因 — 例如「需要麦麦 ≥ 1.4.0」「仅支持 SDK ≤ 2.99.99」「清单协议版本过旧」；这类版本在下拉里是禁用的，看得见原因但选不了

想装某个具体版本（包括比推荐版更旧的版本）时，直接在下拉里选它，再点「安装所选版本」。取消勾选「安装后锁定此版本，阻止自动更新」可以随时改回来。

只能手动降级

自动更新只会往新版本走。如果推荐版比你现在装的版本旧，自动更新会提示「当前已是最新兼容版本，不会自动降级或重装」——想降级或回退，必须在插件详情页手动选中那个版本。

切换 / 降级到另一个版本 ​

在已安装插件的详情页重新选一个版本并安装，就会完成版本切换：

  • 旧插件目录会被整体备份到 plugins/.update_backups/
  • config.toml、config_back/、data/ 会带到新版本，配置不用重填
  • 降级不会回滚插件数据 —— 新版本写过的数据库、状态文件不会还原
  • 切换过程中插件会先停止再重新加载，期间该插件短暂不可用，麦麦核心不需要重启

别在插件目录里改代码再切版本

如果插件仓库里有未提交/已提交的本地代码改动，切换版本会被拒绝并提示「插件存在本地代码修改，请先处理」。需要改动时先备份到别处，或者改用分支安装。

未被版本索引收录的插件 ​

版本列表只覆盖官方索引收录、且发布过 Git Release 的插件。没被收录的仓库安装时会提示「插件尚未收录到版本索引，请先同步插件中心」——这类插件请改用「从 Git 安装」走分支安装，装好后按普通分支插件更新。

按发布版本安装的插件目录里会多一个 .maibot-release.json 安装记录（记录版本、Tag、commit 与是否锁定）。有这份记录的插件不能再直接 git pull 更新，会提示「该插件按发布版本安装，请通过版本选择更新」——要换版本请回插件详情页选。

从仓库安装（git clone） ​

插件市场之外，还有一条「仓库」路径：先在插件站或官方组织里找到插件，再用 Git 地址安装。

去哪里找插件 ​

除了 WebUI 内置的插件市场，你还可以访问 MaiBot 插件站 浏览、搜索社区维护的插件与适配器：

MaiBot 插件站浏览、搜索社区维护的插件与适配器
MaiBot 官方组织官方维护的适配器与示例插件都在这里

从 Git 仓库地址安装 ​

适用于市场搜不到的插件，或你想固定某个分支 / fork。

在插件扩展的「从 Git 安装」里粘贴仓库地址，或在终端手动克隆：

bash
# 通过 WebUI 的「从 Git 安装」粘贴地址，或终端执行：
git clone https://github.com/作者/插件名.git plugins/插件名

示例地址：

https://github.com/作者/插件名

⚠️ 除了 Git 仓库地址，插件扩展页的「更多操作 → 从 ZIP 安装插件」也支持直接上传本地 ZIP 包，见管理插件。

安装后：默认是禁用状态 ​

无论哪种方式，插件写入 plugins/ 后：

  • 文件监听器会发现新插件，并按插件 config_model 生成 config.toml；
  • enabled 默认为 false 的插件需要手动启用才会运行。

到管理插件完成启用与配置。

安全提醒

只安装可信来源的插件。安装前查看仓库的 README、更新时间与 Issue，留意插件申请的权限。第三方插件由各自作者维护，MaiBot 官方不保证其兼容性与安全性。

验证与排错 ​

验证：安装后 WebUI 插件扩展页能看到该插件，且 plugins/<插件名>/config.toml 已生成，说明安装成功；再到管理插件手动启用。

插件列表里没有？

  • 检查目录结构：plugins/<插件名>/ 下必须有 _manifest.json 和插件入口文件，多套一层目录不会被识别

没有生成 config.toml？

  • 插件未声明 config_model 时不会生成配置文件，属正常现象
  • 应该生成却没有时，查看日志中的插件加载错误

启用后没有运行？

  • 对照日志检查 _manifest.json 的 min_version 是否与当前 MaiBot 版本兼容
  • 确认插件声明的依赖已安装
  • 版本被挡住又确定要试时，可临时打开 [debug] force_plugin_compatibility 并重启，见 Manifest 系统 · 强制插件兼容

git clone 失败？

  • 私有仓库需要配置 SSH key 或访问 Token
  • 网络受限时可手动下载插件文件，保持目录结构放入 plugins/<插件名>/

安装指定版本失败？

  • 「插件依赖不满足」— 该版本要求的其他插件或 Python 包没装齐
  • 「插件依赖提醒」— 已装的插件要求这个插件停留在特定版本区间；不会阻止安装，安装 / 切换照常完成，只需留意提醒中可能无法运行的插件
  • 「插件存在本地代码修改，请先处理」— 你在插件目录里改过代码，先备份并还原
  • 「Tag 当前指向的 commit 与版本索引不一致」或「下载的 manifest 与版本索引不一致」— 索引与仓库状态对不上，等索引同步后重试
  • 「版本同步失败：…」— 官方版本索引本身拉取失败，换镜像源或稍后重试

插件市场整个打不开 / 安装转圈？

  • 插件市场支持 HTTPS 域名解析到 Fake-IP 网段 198.18.0.0/15。代理环境下仍无法访问时，检查代理规则、换镜像源，或临时关闭 Fake-IP 模式
  • 所有镜像源都失败时，错误信息末尾会带上每个源的具体原因，按提示排查