Hermes 使用教程
Hermes Agent 插件教程：查找、安装、启用与排错
需要新增工具、拦截工具调用或扩展命令时，可以使用 Hermes 插件。安装前先分清扩展类型，安装后再检查实际启用状态。
本文按 2026 年 9 月 21 日的 Hermes 上游文档编写，聚焦插件管理，不重复 Skills 目录介绍。使用旧版本时先检查 hermes plugins --help；缺少某个子命令不一定是插件损坏。
先判断：你需要插件、Skill 还是 MCP？
| 需求 | 优先考虑 | 要检查什么 |
|---|---|---|
| 让助手按固定步骤写报告、整理资料 | Skill | 指令、附带脚本与所需工具是否可信 |
| 调用已有外部工具服务器 | MCP | 服务地址、授权范围与数据去向 |
| 新增 Python 工具、命令或运行时钩子 | Hermes 插件 | 插件代码、依赖、注册接口与权限 |
例如，整理会议纪要的方法可以写成 Skill；读取文档的能力可能来自 MCP；在工具调用前执行组织规则则可能需要插件钩子。先写清要补充的能力，能帮助你避免安装一整套用不到的扩展。入门工具说明见Hermes 工具与 Skills 指南。
第一步：从官方目录确认来源
Hermes 插件目录提供经过人工审核、固定到特定提交的条目。目录收录是来源信息，不代表第三方代码完全没有风险。安装前读维护者、源码地址、权限、环境变量要求和适用版本。
hermes plugins --help
hermes plugins browse
hermes plugins search memory上面的 memory 是搜索关键词，不是要求安装某个记忆服务。找到合适条目后，使用它的精确目录名称。以 owner/repo 或 Git URL 安装会走自定义来源流程，不能当作目录审核版本。
第二步：先安装，再决定是否启用
下面的 PLUGIN_NAME 是占位符，请替换成你已检查的目录条目名称。命令应在运行该 Hermes 实例的用户和配置环境中执行，不要在宿主机另一个账号的目录里安装。
hermes plugins info PLUGIN_NAME
hermes plugins install PLUGIN_NAME --no-enable
hermes plugins list
hermes plugins capabilities PLUGIN_NAME检查声明的能力与已授权能力是否符合用途，再启用：
hermes plugins enable PLUGIN_NAME
hermes plugins list通用插件的启用名单位于 ~/.hermes/config.yaml 的 plugins.enabled；同名项出现在 plugins.disabled 时，禁用规则优先。不要直接复制别人的整个配置文件，否则可能丢失已有模型和渠道设置。详细规则见上游插件文档。
第三步：重新加载并验证一个小任务
本地 CLI 会话可退出后重新启动；由 Hermes Gateway 管理的自建渠道可使用 hermes gateway restart。插件若有自己的加载说明，按它的说明执行。托管实例通过平台提供的重启入口处理，不在容器里另外启动一套网关。
- 先检查插件列表，确认名称、版本和启用状态符合预期。
- 核对要求的环境变量是否配置到实际服务进程，不要把密钥发给助手作为普通聊天内容。
- 选一个无敏感数据、无外部写入的任务，确认目标工具确实被调用。
- 检查输出是否完成任务，而不是只看助手回答“已经安装”。记录失败时的错误类型，日志分享前脱敏。
插件看得见但用不了，按哪一层排查？
| 现象 | 先检查 | 下一步 |
|---|---|---|
| 没有 plugins 子命令 | 当前运行的 Hermes 版本与可执行文件路径 | 对照该版本文档，按安装方式安排升级 |
| 列表中有插件，但没有工具 | 启用名单、禁用名单及插件类型 | 确认插件本来就提供工具，再重新加载 |
| 加载时报错 | Python 依赖、插件版本、必要环境变量 | 按源码说明补齐依赖，避免全局盲装软件包 |
| CLI 可用，渠道里不可用 | 两个进程是否使用相同用户与配置环境 | 检查网关服务实际读取的目录与环境变量 |
| 只有某个项目无法加载 | 是否放在项目的 .hermes/plugins 目录 | 项目插件默认禁用，仅在可信仓库中按官方说明开启 |
默认用户插件路径是 ~/.hermes/plugins/，项目路径是 .hermes/plugins/。通用插件通常包含 plugin.yaml 和 Python 注册代码。不要为了让未知项目的插件运行，给所有项目全局放开权限。
停用、更新与回退
发现异常时，先运行 hermes plugins disable PLUGIN_NAME 并重新加载服务，观察问题是否消失。更新前记录当前提交和配置、备份插件产生的状态，再按目录或仓库说明升级。删除插件代码不一定会删除第三方服务中的数据，也不能代替撤销已泄露的密钥。
本页的命令和清单结构只适用于 Hermes。OpenClaw 插件使用自身的清单与加载机制；不能把 Hermes 的 Python 插件目录直接复制到 OpenClaw。两种实例都应遵循最小授权，但具体安装方法分别查各自文档。
常见问题
Hermes 插件安装后会自动启用吗？
不要把安装成功当作已经启用。当前上游通用插件需要显式授权；安装命令支持 --no-enable，启用用 hermes plugins enable。部分内置基础设施有不同加载规则，已有安装的升级迁移也可能保留启用状态，应以插件列表和当前配置为准。
Skills、MCP 和插件有什么区别？
Skill 主要描述任务步骤与相关资源；MCP 通过协议暴露外部工具；插件通过代码扩展 Hermes 的工具、钩子或命令。三者可以配合使用，但不能把一个 Skill 文件当成已经安装的插件。
OpenClaw 插件能直接装进 Hermes 吗？
通常不能。Hermes 与 OpenClaw 使用不同的插件清单、运行时与注册接口。只有项目明确提供两个框架的适配版本时，才能分别按各自说明安装。
OpenClaw Launch 托管实例也能照着安装吗？
本文命令针对支持这些命令的自建 Hermes 版本。托管实例的版本、写入权限、依赖安装和重启流程由平台决定；先在仪表盘查看实例支持的入口，不要假定当前上游所有插件都已适配托管环境。