sidebar_position: 11 sidebar_label: “Plugins” title: “Plugins” description: “Extend Hermes with custom tools, hooks, and integrations via the plugin system”

插件

Hermes 拥有插件系统，允许用户在无需修改核心代码的情况下添加自定义工具、钩子功能以及集成方案。

如果您希望为自己、团队或某个项目创建自定义工具，这通常是最佳途径。开发者指南中的添加工具页面介绍了位于 tools/ 目录及 toolsets.py 文件中的内置 Hermes 核心工具。

→ 构建 Hermes 插件 — 提供包含完整可运行示例的分步指导。

快速概览

只需将一个包含 plugin.yaml 配置文件及 Python 代码的目录放入 ~/.hermes/plugins/ 即可：

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # manifest
├── __init__.py      # register() — wires schemas to handlers
├── schemas.py       # tool schemas (what the LLM sees)
└── tools.py         # tool handlers (what runs when called)

启动 Hermes 后，您的自定义工具会与内置工具一同显示，模型可以立即调用这些工具。

最简可用示例

以下是一个完整的插件示例，它新增了一个 hello_world 工具，并通过钩子功能记录每一次工具调用。

~/.hermes/plugins/hello-world/plugin.yaml

name: hello-world
version: "1.0"
description: A minimal example plugin

~/.hermes/plugins/hello-world/__init__.py

"""Minimal Hermes plugin — registers a tool and a hook."""

import json


def register(ctx):
    # --- Tool: hello_world ---
    schema = {
        "name": "hello_world",
        "description": "Returns a friendly greeting for the given name.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Name to greet",
                }
            },
            "required": ["name"],
        },
    }

    def handle_hello(params, **kwargs):
        del kwargs
        name = params.get("name", "World")
        return json.dumps({"success": True, "greeting": f"Hello, {name}!"})

    ctx.register_tool(
        name="hello_world",
        toolset="hello_world",
        schema=schema,
        handler=handle_hello,
        description="Return a friendly greeting for the given name.",
    )

    # --- Hook: log every tool call ---
    def on_tool_call(tool_name, params, result):
        print(f"[hello-world] tool called: {tool_name}")

    ctx.register_hook("post_tool_call", on_tool_call)

将这两个文件放入 ~/.hermes/plugins/hello-world/ 目录中，重启 Hermes 后，模型即可立即调用 hello_world 函数。每次工具被调用时，该钩子都会打印一条日志。

位于 ./.hermes/plugins/ 下的项目级插件默认处于禁用状态。只有在信任的代码库中使用时，才需在启动 Hermes 之前设置 HERMES_ENABLE_PROJECT_PLUGINS=true 来启用它们。

插件能实现的功能

以下所有 ctx.* API 都可在插件的 register(ctx) 函数中使用。

插件发现机制

当插件名称冲突时，后加载的来源会覆盖先加载的来源。因此，若用户自定义插件与内置插件名称相同，后者将被替换。

插件子类别

对于每种来源，Hermes 还能识别用于将插件路由到相应发现系统的子目录：

位于 ~/.hermes/plugins/model-providers/<name>/ 和 ~/.hermes/plugins/memory/<name>/ 的用户自定义插件会覆盖同名内置插件 —— 在 register_provider() / register_memory_provider() 中遵循“后写入者胜出”的原则。只需将相关目录放入指定位置，即可在无需修改任何代码库配置的情况下替换内置插件。

插件为可选功能（少数情况除外）

通用插件及用户安装的后端默认处于禁用状态 —— 系统虽能发现它们（因此会显示在 hermes plugins 和 /plugins 中），但除非你在 ~/.hermes/config.yaml 的 plugins.enabled 列表中添加该插件的名称，否则其包含的钩子或工具都不会被加载。这一设计旨在防止未经用户明确许可就运行第三方代码。

plugins:
  enabled:
    - my-tool-plugin
    - disk-cleanup
  disabled:       # optional deny-list — always wins if a name appears in both
    - noisy-plugin

三种切换状态的方式：

hermes plugins                    # interactive toggle (space to check/uncheck)
hermes plugins enable <name>      # add to allow-list
hermes plugins disable <name>     # remove from allow-list + add to disabled

在运行 hermes plugins install owner/repo 命令后，系统会询问“现在启用 ‘name’ 吗？[y/N]”——默认答案为“否”。若使用 --enable 或 --no-enable 参数进行脚本化安装，则可跳过此提示。

allow-list 不管控的内容

有几类插件不受 plugins.enabled 的限制——它们属于 Hermes 的内置功能，若被默认禁用将会影响核心功能：

简而言之：那些“始终可用”的预装基础设施会自动加载；而第三方通用插件则需要手动启用。 plugins.enabled 的 allow-list 专门用于管控用户放入 ~/.hermes/plugins/ 目录中的任意自定义代码。

现有用户的迁移方案

当您升级到支持插件可选启用的 Hermes 版本（配置架构 v21 及以上）时，任何已安装在 ~/.hermes/plugins/ 下且未被列入 plugins.disabled 的用户插件，都会自动继承为已启用状态，无需额外操作，您的现有设置依然可以正常使用。而那些预装的独立插件则不会自动继承此状态——即便是现有用户也必须手动进行启用操作。（由于这些预装的平台/后端插件从来就没有被设为受限状态，因此根本无需此类迁移。）

可用的钩子函数

插件可以为这些生命周期事件注册回调函数。详细信息、回调签名及示例请参阅 事件钩子页面。

插件类型

Hermes 共有四种类型的插件：

内存提供者和上下文引擎属于提供者插件——同一类型中只能有一个处于活跃状态。模型提供者也属于插件类别，但允许多个同时加载；用户需通过 --provider 参数或 config.yaml 逐个选择使用。而通用插件则可以以任意组合方式启用。

可插接的接口——对应需求的选择指南

上表列出了四种插件类别，但在“通用插件”中，PluginContext 还提供了多个独立的扩展点；此外，Hermes 还支持 Python 插件系统之外的扩展方式（如基于配置的后端、Shell 钩子命令、外部服务器等）。请参考下表，找到适合您所需功能的文档：

:::note 并非所有功能都必须通过 Python 插件实现。有些扩展接口特意采用了基于配置的 Shell 命令方式（如文本转语音、语音转文本、Shell 钩子函数），这样用户现有的任何 CLI 工具都可以直接作为插件使用，无需编写 Python 代码。还有一些是外部服务器（如 MCP），代理会连接到这些服务器并自动注册其提供的工具。此外还有一种是可直接插入的目录结构（即网关钩子），它们拥有独立的清单格式。请根据您的实际应用场景选择合适的集成方式；上表中的开发指南分别涵盖了相关占位符配置、发现机制及示例代码。

::

NixOS 声明式插件安装

在 NixOS 系统中，可以通过模块选项以声明式方式安装插件——无需再使用 hermes plugins install 命令。详细信息请参阅 NixOS 安装指南。

services.hermes-agent = {
  # Directory plugin (source tree with plugin.yaml)
  extraPlugins = [ (pkgs.fetchFromGitHub { ... }) ];
  # Entry-point plugin (pip package)
  extraPythonPackages = [ (pkgs.python312Packages.buildPythonPackage { ... }) ];
  # Enable in config
  settings.plugins.enabled = [ "my-plugin" ];
};

声明式插件会以 nix-managed- 作为前缀进行链接——它们与手动安装的插件共存，且当从 Nix 配置中移除时会被自动清理。

插件管理

hermes plugins                               # unified interactive UI
hermes plugins list                          # table: enabled / disabled / not enabled
hermes plugins install user/repo             # install from Git, then prompt Enable? [y/N]
hermes plugins install user/repo --enable    # install AND enable (no prompt)
hermes plugins install user/repo --no-enable # install but leave disabled (no prompt)
hermes plugins update my-plugin              # pull latest
hermes plugins remove my-plugin              # uninstall
hermes plugins enable my-plugin              # add to allow-list
hermes plugins disable my-plugin             # remove from allow-list + add to disabled

交互式用户界面

运行 hermes plugins 且不指定任何参数时，将会打开一个综合性的交互式界面：

Plugins
  ↑↓ navigate  SPACE toggle  ENTER configure/confirm  ESC done

  General Plugins
 → [✓] my-tool-plugin — Custom search tool
   [ ] webhook-notifier — Event hooks
   [ ] disk-cleanup — Auto-cleanup of ephemeral files [bundled]

  Provider Plugins
     Memory Provider          ▸ honcho
     Context Engine           ▸ compressor

• 通用插件部分 — 支持复选框操作，可用空格键切换状态。选中状态表示该插件被包含在 plugins.enabled 中，未选中则表示被列入 plugins.disabled（即明确禁用）。
• 提供商插件部分 — 显示当前的选择状态。按下回车键可进入单选菜单，在其中选择要启用的提供商。
• 打包在一起的插件会以 [bundled] 标签显示在同一列表中。

所选的提供商插件信息会被保存到 config.yaml 文件中：

memory:
  provider: "honcho"      # empty string = built-in only

context:
  engine: "compressor"    # default built-in compressor

已启用、已禁用与未启用状态

插件存在以下三种状态之一：

新安装或随包提供的插件默认处于 not enabled 状态。使用 hermes plugins list 可查看这三种不同状态，从而区分哪些是明确被禁用的，哪些只是待启用状态。

在正在运行的会话中，通过 /plugins 可查看当前已加载的插件列表。

注入消息

插件可通过 ctx.inject_message() 将消息注入到当前对话中：

ctx.inject_message("New data arrived from the webhook", role="user")

签名： ctx.inject_message(content: str, role: str = "user") -> bool

工作原理：

• 若智能体处于空闲状态（正在等待用户输入），该消息将被排队作为下一个输入，从而开启新的对话轮次。
• 若智能体正处于对话进行中（正在执行任务），该消息会中断当前操作——其效果等同于用户输入新消息后按下回车键。
• 对于非 "user" 角色的消息，内容前会加上 [role] 前缀（例如 [system] ...）。
• 若消息成功排队，则返回 True；若不存在 CLI 参考对象（例如在网关模式下），则返回 False。

此功能使得远程控制查看器、消息桥接工具或 webhook 接收器等插件能够从外部来源向对话中注入消息。

::note inject_message 仅在 CLI 模式下可用。在网关模式下没有 CLI 参考对象，因此该方法会返回 False。

::

有关处理程序契约、架构格式、钩子行为、错误处理以及常见错误等方面的详细信息，请参阅**完整指南**。