sidebar_position: 10 title: “Model Provider Plugins” description: “How to build a model provider (inference backend) plugin for Hermes Agent”

构建模型提供者插件

模型提供者插件用于指定推理后端——可以是兼容 OpenAI 的接口、Anthropic Messages 服务器、Codex 风格的 Responses API，或是 Bedrock 原生界面——Hermes 可通过这些后端来路由 AIAgent 调用。所有内置提供者（如 OpenRouter、Anthropic、GMI、DeepSeek、Nvidia 等）均以此类插件的形式提供。第三方开发者只需在 $HERMES_HOME/plugins/model-providers/ 目录下创建相应文件夹，而无需对代码库进行任何修改，即可添加自己的插件。

::提示 模型提供者插件属于第三种提供者插件。另外两种分别是内存提供者插件（用于跨会话知识传递）和上下文引擎插件（用于上下文压缩策略）。这三种插件均遵循相同的实现方式：只需创建文件夹、定义配置文件，无需修改代码库。

::

发现机制的工作原理

每当有代码调用 get_provider_profile() 或 list_providers() 时，providers/__init__.py._discover_providers() 函数才会被延迟加载执行。插件发现顺序如下：

1. 内置插件——位于 <repo>/plugins/model-providers/<name>/ 目录中，随 Hermes 一起提供
2. 用户自定义插件——放置于 $HERMES_HOME/plugins/model-providers/<name>/ 目录下，可放入任意位置；后续会话无需重启即可使用
3. 旧版单文件插件——位于 <repo>/providers/<name>.py 目录中，为非代码库内编辑的安装方式提供兼容支持

由于 register_provider() 函数遵循“最后写入者胜出”的原则，用户自定义插件会覆盖同名内置插件。因此，只需在 $HERMES_HOME/plugins/model-providers/gmi/ 目录下创建新文件夹，即可替换内置的 GMI 配置文件，而无需修改代码库。

目录结构

plugins/model-providers/my-provider/
├── __init__.py       # Calls register_provider(profile) at module-level
├── plugin.yaml       # kind: model-provider + metadata (optional but recommended)
└── README.md         # Setup instructions (optional)

唯一必需的文件是 __init__.py。plugin.yaml 会被 hermes plugins 用于元数据解析，同时也会被通用的 PluginManager 使用，以便将插件路由至对应的加载器；若没有该文件，通用加载器则会退而采用基于源文本的启发式方法进行加载。

最简示例——一个简单的 API 密钥提供器

# plugins/model-providers/acme-inference/__init__.py
from providers import register_provider
from providers.base import ProviderProfile

acme = ProviderProfile(
    name="acme-inference",
    aliases=("acme",),
    display_name="Acme Inference",
    description="Acme — OpenAI-compatible direct API",
    signup_url="https://acme.example.com/keys",
    env_vars=("ACME_API_KEY", "ACME_BASE_URL"),
    base_url="https://api.acme.example.com/v1",
    auth_type="api_key",
    default_aux_model="acme-small-fast",
    fallback_models=(
        "acme-large-v3",
        "acme-medium-v3",
        "acme-small-fast",
    ),
)

register_provider(acme)

# plugins/model-providers/acme-inference/plugin.yaml
name: acme-inference
kind: model-provider
version: 1.0.0
description: Acme Inference — OpenAI-compatible direct API
author: Your Name

就这样。放入这两个文件后，无需其他修改即可实现以下自动关联：

ProviderProfile 字段

完整定义见 providers/base.py，其中最常用的字段如下：

可覆盖的钩子函数

如需处理特殊需求，可对 ProviderProfile 进行子类化：

from typing import Any
from providers.base import ProviderProfile

class AcmeProfile(ProviderProfile):
    def prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
        """Provider-specific message preprocessing. Runs after codex
        sanitization, before developer-role swap. Default: pass-through."""
        # Example: Qwen normalizes plain-text content to a list-of-parts
        # array and injects cache_control; Kimi rewrites tool-call JSON
        return messages

    def build_extra_body(self, *, session_id=None, **context) -> dict:
        """Provider-specific extra_body fields merged into the API call.
        Context includes: session_id, provider_preferences, model, base_url,
        reasoning_config. Default: empty dict."""
        # Example: OpenRouter's provider-preferences block,
        # Gemini's thinking_config translation.
        return {}

    def build_api_kwargs_extras(self, *, reasoning_config=None, **context):
        """Returns (extra_body_additions, top_level_kwargs). Needed when some
        fields go top-level (Kimi's reasoning_effort, OpenRouter's verbosity for
        adaptive Anthropic models) and some go in extra_body (OpenRouter's
        reasoning dict). Default: ({}, {})."""
        return {}, {}

    def fetch_models(self, *, api_key=None, timeout=8.0) -> list[str] | None:
        """Live catalog fetch. Default hits {models_url or base_url}/models with
        Bearer auth. Override for: custom auth (Anthropic), no REST endpoint
        (Bedrock → None), or public/unauthenticated catalogs (OpenRouter)."""
        return super().fetch_models(api_key=api_key, timeout=timeout)

Hook 参考示例

以下是些用于处理常用表达的插件示例：

用户自定义设置——无需修改代码库即可替换内置插件

假设您希望将 gmi 指向自己的私有测试环境端点。只需创建文件 ~/.hermes/plugins/model-providers/gmi/__init__.py 即可：

from providers import register_provider
from providers.base import ProviderProfile

register_provider(ProviderProfile(
    name="gmi",
    aliases=("gmi-cloud", "gmicloud"),
    env_vars=("GMI_API_KEY",),
    base_url="https://gmi-staging.internal.example.com/v1",
    auth_type="api_key",
    default_aux_model="google/gemini-3.1-flash-lite-preview",
))

在下一个会话中，get_provider_profile("gmi").base_url 会返回测试环境地址。无需修改代码库，也无需重新构建。由于用户插件是在内置插件之后被发现的，因此用户调用的 register_provider() 方法会优先生效。

api_mode 选择

系统支持四种取值，Hermes会根据以下规则进行选择：

1. 用户显式指定（当设置了 config.yaml 中的 model.api_mode 时）
2. OpenCode 根据模型类型进行的自动分配（Zen 和 Go 模型使用 opencode_model_api_mode）
3. URL 自动检测——以 /anthropic 结尾则对应 anthropic_messages，以 api.openai.com 结尾则对应 codex_responses，以 api.x.ai 结尾也对应 codex_responses，Kimi 域名中的 /coding 路径则对应 chat_completions
4. 当 URL 检测无结果时，作为兜底方案使用配置文件中的 api_mode 设置
5. 默认值为 chat_completions

请将 profile.api_mode 设置为你的服务提供商所使用的默认值——这仅作为参考。用户自定义的 URL 设置仍会优先生效。

认证类型

auth_type 决定了哪些代码路径会将你的服务提供商视为“简单 API 密钥提供商”——即便 auth_type 不是 api_key，PluginManager 仍会记录相关配置，但 Hermes 的 CLI 级自动化功能（如校验流程、--provider 参数以及设置向导）可能会跳过对该提供商的处理。

发现时机

服务提供商的发现机制为延迟触发式——仅在进程中的首次调用 get_provider_profile() 或 list_providers() 时才会进行。实际上，这一操作会在启动阶段尽早执行（auth.py 模块在加载时会立即扩展 PROVIDER_REGISTRY）。如果你需要确认自己的插件已成功加载，可运行相应命令：

hermes doctor

——若认证方式 auth_type="api_key" 设置成功，则会在“Provider Connectivity”部分显示相应的配置，并包含一个 /models 探测项。

如需通过程序进行检测：

from providers import list_providers
for p in list_providers():
    print(p.name, p.base_url, p.api_mode)

测试您的插件

请将 HERMES_HOME 指向一个临时目录，以避免污染您的实际配置文件：

export HERMES_HOME=/tmp/hermes-plugin-test
mkdir -p $HERMES_HOME/plugins/model-providers/my-provider
cat > $HERMES_HOME/plugins/model-providers/my-provider/__init__.py <<'EOF'
from providers import register_provider
from providers.base import ProviderProfile
register_provider(ProviderProfile(
    name="my-provider",
    env_vars=("MY_API_KEY",),
    base_url="https://api.my-provider.example.com/v1",
    auth_type="api_key",
))
EOF

export MY_API_KEY=your-test-key
hermes -z "hello" --provider my-provider -m some-model

通用的 PluginManager 集成方式

通用的 PluginManager（即 hermes plugins 所操作的组件）能够识别模型提供者插件，但并不会直接导入它们——其生命周期由 providers/__init__.py 负责管理。该管理器会记录插件的元数据以便后续查询，并根据 kind: model-provider 对其进行分类。当您将一个未标记的用户插件放入 $HERMES_HOME/plugins/ 目录中，且该插件恰好调用了带有 ProviderProfile 参数的 register_provider 函数时，管理器会通过源代码特征自动将其归类为 kind: model-provider——这样一来，即便没有 plugin.yaml 文件，插件仍能被正确路由。

通过 pip 分发

与普通的 Hermes 插件一样，模型提供者也可以以 pip 包的形式分发。只需在您的 pyproject.toml 文件中添加一个入口点即可：

[project.entry-points."hermes_agent.plugins"]
acme-inference = "acme_hermes_plugin:register"

……其中 acme_hermes_plugin:register 是一个调用 register_provider(profile) 的函数。通用的 PluginManager 会在 discover_and_load() 阶段加载入口插件。对于类型为 model-provider 的 pip 插件，您仍需在清单中明确指定该类型（或依赖源文本分析机制）。

有关完整的入口点配置方式，请参阅 构建 Hermes 插件。

相关页面

• Provider 运行时 —— 解析优先级及各层级读取配置文件的位置
• 添加 Provider —— 新推理后端的端到端操作清单（涵盖快速插件路径以及完整的 CLI/身份验证集成）
• 内存 Provider 插件
• 上下文引擎插件
• 构建 Hermes 插件 —— 通用插件开发指南