AstrBot 插件

插件是为 AstrBot 增加功能的扩展程序。安装插件后，你可以让机器人支持新的指令、接入外部服务，或为 AI 提供新的工具，而不必修改 AstrBot 本体的代码。

例如，你希望机器人查询天气、订阅消息、生成图片，或在聊天中操作某个服务，就可以先在插件市场中寻找相应的插件。使用插件通常不需要编程；只有开发或修改插件时才需要写代码。

本页从安装和使用开始介绍。如果你已经准备自己开发插件，可以直接阅读插件开发指南。

插件是什么，有什么用？

AstrBot 负责接收消息、连接模型、管理对话等基础工作；插件通过 AstrBot 提供的接口，在这些流程中加入自己的功能。在开发文档和代码中，插件也称为 Star。

能力	使用方式与例子
聊天指令	发送指定指令触发功能，例如查询信息、生成内容或进行管理操作。指令名称和参数由插件定义。
AI 工具	为 Agent 提供可调用的工具，例如查询某个服务的数据。用户用自然语言提出需求，由模型决定是否调用。
消息处理	监听消息或其他事件，根据规则回复、处理内容，或调整 AI 请求和回复。
外部服务集成	连接第三方 API、数据库或业务系统。部分插件需要配置 API Key、账号或服务地址。
管理页面与技能	插件可以提供自己的 WebUI 页面，也可以随插件分发 Skills，帮助 Agent 按特定流程完成任务。

这些是插件机制支持的能力，不是每个插件都包含全部功能。实际用途、支持的平台、是否需要模型以及配置要求，请以作者的说明为准。

插件与 AI 的关系

普通指令或消息处理插件不一定需要 AI 模型。提供 AI 工具的插件通常需要能够调用工具的模型，并在当前使用的人格中允许相关工具。安装一个插件，也不代表它的所有功能都会自动参与每次对话。

第一次使用：安装一个插件

建议第一次从插件市场安装，完整走一遍下面的流程。

1. 打开插件市场

进入 AstrBot 管理面板，点击左侧的 插件，在顶部选择 插件 标签，再切换到 插件市场。

• 已安装：管理已经安装到当前 AstrBot 的插件。
• 插件市场：浏览、搜索和安装插件。

同一工作区顶部还有 技能、MCP 和 管理行为 标签，分别用于管理 Skills、MCP 服务以及插件注册的指令、工具等行为。

2. 找到合适的插件

在市场搜索框中输入插件名称或功能关键词，也可以按 AI 增强、娱乐、效率、外部集成、生活实用、其他 分类筛选。点击感兴趣的插件查看详情，先确认：

• 功能和用法：是否解决你的需求，安装后通过指令、自然语言还是其他方式使用。
• 支持平台：是否支持你接入的消息平台。某些功能依赖特定平台的接口。
• AstrBot 版本要求：当前版本是否满足插件要求。
• 配置与依赖：是否需要 API Key、第三方服务、额外程序或特定部署环境。

遇到说明不完整的插件，可以打开其仓库，阅读 README 和使用文档。Star 数、下载量和更新时间可以辅助筛选，但不能代替兼容性和使用说明。

3. 安装并确认加载成功

点击插件的 安装 按钮，确认安装来源后等待操作完成。回到 已安装 页面，找到该插件，确认插件已打开且没有加载错误。

如果出现在 加载失败插件 列表中，先查看错误信息，按照下文的常见问题处理，再点击 重载。

4. 填写插件配置

如果插件需要配置，点击插件卡片上的齿轮图标（插件配置），按作者说明填写参数并保存。例如，外部服务插件可能需要 API Key、服务地址或订阅目标。

没有额外配置项的插件可以跳过这一步。不要把插件要求的服务凭据填写到无关的模型配置中。

5. 按说明触发功能

在已经接入 AstrBot 的聊天平台中，按照插件文档测试一个最简单的功能：

• 指令插件：发送作者提供的指令及参数。也可以发送 /help 查看当前启用的指令，或在 插件 → 管理行为 → 指令 中查看和管理。
• AI 工具插件：向机器人描述需求，并确认当前模型支持工具调用、当前人格允许使用对应工具。
• 事件或自动处理插件：按作者说明触发相应事件，例如发送符合规则的消息。

指令前缀

本文使用默认的 / 前缀。如果你把唤醒前缀改成了 !，则应使用 !help，插件指令也要使用对应的前缀。部分指令还要求 AstrBot 管理员权限，具体以插件说明和指令管理中的设置为准。

插件市场

插件市场是发现和安装社区插件的入口。安装到 AstrBot 后，插件在 已安装 页面统一管理；市场本身不是插件运行的环境。

市场提供搜索、分类和排序。新人通常使用 默认插件源 即可。有明确需要时，可以通过 插件源管理 添加或切换自定义插件源；插件源决定你浏览到的插件列表，添加一个源不等于安装其中的全部插件。

安装前了解来源

插件会在 AstrBot 所在的 Python 环境中运行，请安装你信任的插件。插件市场中的收录不代表对插件稳定性和安全性的保证。Agent 的本地隔离设置用于限制 Agent 执行，不会自动隔离任意插件代码。

如果你是作者，市场底部的 提交我的插件 会打开 AstrBot Cloud 插件发布页面。具体流程见发布插件到插件市场。

从仓库或文件安装

市场中没有收录的插件，或者作者提供了指定版本的安装包，也可以手动安装。在 已安装 或 插件市场 页面，点击右下角的 安装插件（+）。

从链接安装

1. 选择 从链接安装。
2. 填入作者提供的插件 Git 仓库地址，例如 https://github.com/作者名/插件仓库名。
3. 确认来源并安装，完成后在 已安装 页面检查状态。

这里填写的是插件代码仓库地址，不是插件介绍文章、管理面板地址或任意网页链接。

从文件安装

1. 从插件作者处获取插件的 .zip 安装包。
2. 选择 从文件安装，上传该 ZIP 文件并安装。
3. 完成后检查加载状态，按插件说明配置和使用。

安装包需要包含完整的 AstrBot 插件文件。单独的 Python 文件、MCP 配置或 Skills 压缩包不能当作插件安装包使用。通过文件安装也不代表离线可用：安装依赖或访问外部服务时仍可能需要网络。

配置与管理

插件参数与可用范围

下面几处设置控制的是不同的事情：

设置位置	控制什么
插件 → 插件 → 对应插件的齿轮图标	配置该插件自己的参数，例如服务地址、密钥和功能开关。这里的参数通常是该 AstrBot 实例共用的，插件也可能自行提供更细的设置。
配置文件 → 选择配置文件 → 插件	选择该配置文件可以使用的插件。默认使用全部未被关闭的插件，也可以只选部分插件。修改后保存配置。
人格中的人格能力	选择当前人格可以使用的工具与技能。插件提供 AI 工具时，需要检查这里是否允许该工具。
插件 → 管理行为	查看和管理已注册的指令、函数工具等行为；指令可以有自己的启用状态、名称和权限设置。

先确认插件已打开，再检查当前会话使用的配置文件和人格。 在配置文件中勾选一个已关闭的插件，不会让它重新打开。如果你给不同平台或会话分配了不同配置文件，也要修改实际生效的那一份。

更新、重载、关闭与删除

在 已安装 页面，可以对插件执行以下操作：

操作	何时使用
更新	获取作者发布的新代码。更新前阅读变更说明，重要插件建议先备份配置和数据。
重载	重新加载当前已有的插件代码，例如修复依赖或修改代码后。重载不会下载新版本。
打开 / 关闭插件	启用或停用插件；暂时不用时可以关闭，保留文件以便以后使用。
查看行为	查看该插件注册的指令、工具等，了解它提供了哪些入口。
删除插件	卸载不再需要的插件。删除弹窗中可分别选择是否同时删除插件配置文件和持久化数据。

删除时请留意 同时删除插件配置文件 和 同时删除插件持久化数据 两个选项。需要保留设置或业务数据时，不要勾选对应选项。

插件、MCP 与 Skills 有什么区别？

方式	主要用途	进一步了解
插件	用 Python 接入 AstrBot 的消息和 AI 流程，可提供指令、工具、事件处理、页面等。	本页及插件开发指南
MCP	通过 MCP 协议接入独立的工具服务，让模型调用其提供的工具。	MCP
Skills	提供任务说明、流程、参考材料和脚本，让 Agent 按特定方法完成任务。	技能 Skills

它们可以配合使用。例如，一个插件可以提供工具并附带指导 Agent 使用工具的 Skill。插件内置的 Skills 会显示在 插件 → 技能 中，可以启用或禁用，但文件由插件管理，不能在本地 Skills 页面直接编辑或删除。

常见问题

安装失败，或市场打不开

先查看安装弹窗中的错误与日志。如果是下载超时或连接失败，检查 运行 AstrBot 的设备或容器 是否能访问插件源、代码仓库和依赖下载服务；你的浏览器能打开仓库，不代表 AstrBot 所在环境也能访问。

从链接安装时确认仓库地址正确；从文件安装时确认 ZIP 包完整。遇到版本不兼容提示，应先确认插件要求，选择兼容的 AstrBot 或插件版本。

插件加载失败

在 加载失败插件 中查看错误，或进入 数据与日志 → 日志 查看详细信息。

• 缺少 Python 依赖：按插件文档安装对应依赖；日志页面也提供安装 Pip 库的入口。依赖要安装到 AstrBot 实际运行的 Python 环境中，Docker 部署时不要只安装在宿主机上。
• 缺少外部程序或服务：按照插件说明配置对应程序、账号或服务。
• 代码报错或版本不兼容：检查插件和 AstrBot 版本，查看作者的已知问题，必要时向作者反馈。

修复后点击 重载 再试，无需为了重载一个失败插件重启整个 AstrBot。

安装成功，但发送消息没有反应

按下面的顺序检查：

1. 插件是否已打开，且没有加载错误。
2. 当前会话生效的配置文件是否允许该插件。
3. 插件参数是否填写完整，外部服务是否可用。
4. 使用方式是否正确：指令名称、前缀、参数、平台和权限是否符合要求。
5. 如果是 AI 工具，当前模型是否支持工具调用，当前人格是否允许相关工具。

不是所有插件都有聊天指令，也不是所有工具都会在每条消息中被模型调用。建议先使用作者提供的最小示例验证，再尝试更复杂的需求。

如何反馈问题？

优先通过插件仓库的 Issues 或作者注明的渠道反馈，附上 AstrBot 版本、插件版本、消息平台、部署方式、复现步骤和相关错误日志。不要公开 API Key、Token 等凭据。

开发自己的插件

如果现有插件无法满足需求，你可以用 Python 开发自己的插件。建议具备基础的 Python 和 Git / GitHub 使用经验，再按以下顺序学习：

1. 创建项目：按照插件开发指南，从 helloworld 模板创建仓库。建议以 astrbot_plugin_ 开头命名。
2. 接入开发环境：将仓库放到 AstrBot 的 data/plugins/<插件目录>/ 中，填写 metadata.yaml，让 AstrBot 识别插件名称、版本和作者等信息。
3. 实现一个最小功能：先完成一个接收消息并回复的指令。参考消息事件监听和发送消息，在自己的机器人中测试。
4. 逐步增加能力：根据需要添加AI 工具与模型交互、插件配置、数据存储或插件页面。修改代码后可以通过 WebUI 重载插件。
5. 整理使用说明：在 README 中说明功能、安装方法、指令或工具、配置项、依赖、支持的平台及版本要求，声明所需的 Python 依赖并补全插件元数据。
6. 发布到市场：将代码推送到 GitHub，按插件发布文档通过 AstrBot Cloud提交插件。发布需要注册 AstrBot Cloud 账号。

开发指南包含完整的环境准备和 API 用法。第一次开发时，先让一个简单指令正常工作，再逐步加入配置、工具或外部服务，会更容易定位问题。