> 📖 本文档翻译自 Adding Providers > 最后更新：2026-04-16

---

sidebar_position: 5 title: "添加 Provider" description: "如何向 Hermes Agent 添加新的推理 Provider——认证、运行时解析、CLI 流程、适配器、测试和文档"

添加 Provider

Hermes 已经可以通过自定义 Provider 路径与任何 OpenAI 兼容端点通信。除非你想为该服务提供第一方用户体验，否则不要添加内置 Provider：

• Provider 特定的认证或 Token 刷新
• 策划的模型目录
• 设置 / hermes model 菜单项
• provider:model 语法的 Provider 别名
• 需要 Adapter(适配器)的非 OpenAI API 格式

如果 Provider 只是"另一个 OpenAI 兼容的 Base URL 和 API 密钥"，命名自定义 Provider 可能就够了。

心智模型

内置 Provider 需要在多个层面保持一致：

1. hermes_cli/auth.py 决定如何查找凭据。
2. hermes_cli/runtime_provider.py 将其转换为运行时数据：
   • provider
   • api_mode
   • base_url
   • api_key
   • source
3. run_agent.py 使用 api_mode 决定如何构建和发送请求。
4. hermes_cli/models.py 和 hermes_cli/main.py 使 Provider 出现在 CLI 中。（hermes_cli/setup.py 自动委托给 main.py——不需要在那里修改。）
5. agent/auxiliary_client.py 和 agent/model_metadata.py 保持辅助任务和 Token 预算正常工作。

重要的抽象是 api_mode。

• 大多数 Provider 使用 chat_completions。
• Codex 使用 codex_responses。
• Anthropic 使用 anthropic_messages。
• 新的非 OpenAI 协议通常意味着添加新适配器和新 api_mode 分支。

首先选择实现路径

路径 A——OpenAI 兼容 Provider

当 Provider 接受标准 chat-completions 风格请求时使用此路径。

典型工作：

• 添加认证元数据
• 添加模型目录/别名
• 添加运行时解析
• 添加 CLI 菜单连接
• 添加辅助模型默认值
• 添加测试和用户文档

通常不需要新适配器或新 api_mode。

路径 B——原生 Provider

当 Provider 的行为不像 OpenAI chat completions 时使用此路径。

当前代码树中的示例：

• codex_responses
• anthropic_messages

此路径包括路径 A 的所有内容，再加上：

• agent/ 中的 Provider 适配器
• run_agent.py 中用于请求构建、分发、用量提取、中断处理和响应规范化的分支
• 适配器测试

文件检查清单

每个内置 Provider 都需要的

1. hermes_cli/auth.py
2. hermes_cli/models.py
3. hermes_cli/runtime_provider.py
4. hermes_cli/main.py
5. agent/auxiliary_client.py
6. agent/model_metadata.py
7. 测试
8. website/docs/ 下的用户文档

:::tip 提示 hermes_cli/setup.py 不需要修改。设置向导将 Provider/模型选择委托给 main.py 中的 select_provider_and_model()——在那里添加的任何 Provider 自动在 hermes setup 中可用。 :::

原生/非 OpenAI Provider 额外需要的

10. agent/<provider>_adapter.py
11. run_agent.py
12. 如果需要 Provider SDK 则修改 pyproject.toml

步骤 1：选择一个规范 Provider ID

选择一个 Provider ID 并在各处使用。

代码库中的示例：

• openai-codex
• kimi-coding
• minimax-cn

同一个 ID 应该出现在：

• hermes_cli/auth.py 中的 PROVIDER_REGISTRY
• hermes_cli/models.py 中的 _PROVIDER_LABELS
• hermes_cli/auth.py 和 hermes_cli/models.py 中的 _PROVIDER_ALIASES
• hermes_cli/main.py 中的 CLI --provider 选项
• 设置/模型选择分支
• 辅助模型默认值
• 测试

如果这些文件之间的 ID 不同，Provider 会感觉半成品：认证可能工作但 /model、setup 或运行时解析会静默遗漏它。

步骤 2：在 hermes_cli/auth.py 中添加认证元数据

对于 API 密钥 Provider，向 PROVIDER_REGISTRY 添加一个 ProviderConfig 条目，包含：

• id
• name
• auth_type="api_key"
• inference_base_url
• api_key_env_vars
• 可选的 base_url_env_var

还要在 _PROVIDER_ALIASES 中添加别名。

以现有 Provider 作为模板：

• 简单 API 密钥路径：Z.AI、MiniMax
• 带端点检测的 API 密钥路径：Kimi、Z.AI
• 原生 Token 解析：Anthropic
• OAuth/认证存储路径：Nous、OpenAI Codex

需要回答的问题：

• Hermes 应该检查哪些环境变量，按什么优先级顺序？
• Provider 是否需要 Base URL 覆盖？
• 是否需要端点探测或 Token 刷新？
• 凭据缺失时认证错误应该说什么？

如果 Provider 需要的不仅仅是"查找 API 密钥"，添加专用的凭据解析器而不是将逻辑塞到不相关的分支中。

步骤 3：在 hermes_cli/models.py 中添加模型目录和别名

更新 Provider 目录，使 Provider 在菜单和 provider:model 语法中工作。

典型编辑：

• _PROVIDER_MODELS
• _PROVIDER_LABELS
• _PROVIDER_ALIASES
• list_available_providers() 中的 Provider 显示顺序
• 如果 Provider 支持实时 /models 获取则更新 provider_model_ids()

如果 Provider 暴露实时模型列表，优先使用它并将 _PROVIDER_MODELS 作为静态回退。

这个文件也使得以下输入工作：

anthropic:claude-sonnet-4-6
kimi:model-name

如果这里缺少别名，Provider 可能正确认证但在 /model 解析中仍然失败。

步骤 4：在 hermes_cli/runtime_provider.py 中解析运行时数据

resolve_runtime_provider() 是 CLI、网关、定时任务、ACP 和辅助客户端使用的共享路径。

添加一个返回至少包含以下内容的字典的分支：

{
    "provider": "your-provider",
    "api_mode": "chat_completions",  # 或你的原生模式
    "base_url": "https://...",
    "api_key": "***",
    "source": "env|portal|auth-store|explicit",
    "requested_provider": requested_provider,
}

如果 Provider 是 OpenAI 兼容的，api_mode 通常应保持 chat_completions。

注意 API 密钥优先级。Hermes 已包含避免将 OpenRouter 密钥泄露到不相关端点的逻辑。新 Provider 应同样明确哪个密钥发送到哪个 Base URL。

步骤 5：在 hermes_cli/main.py 中连接 CLI

Provider 只有出现在交互式 hermes model 流程中才能被发现。

在 hermes_cli/main.py 中更新：

• provider_labels 字典
• select_provider_and_model() 中的 providers 列表
• Provider 分发（if selected_provider == ...）
• --provider 参数选项
• 如果 Provider 支持登录/登出流程则添加相应选项
• _model_flow_<provider>() 函数，或者如果适合则复用 _model_flow_api_key_provider()

:::tip 提示 hermes_cli/setup.py 不需要修改——它调用 main.py 中的 select_provider_and_model()，所以你的新 Provider 自动在 hermes model 和 hermes setup 中都出现。 :::

步骤 6：保持辅助调用正常工作

这里有两个文件很重要。

agent/auxiliary_client.py

如果这是直接 API 密钥 Provider，向 _API_KEY_PROVIDER_AUX_MODELS 添加一个廉价/快速的默认辅助模型。

辅助任务包括：

• 视觉摘要
• 网页提取摘要
• 上下文压缩摘要
• 会话搜索摘要
• 内存刷新

如果 Provider 没有合适的辅助默认值，辅助任务可能回退不佳或意外使用昂贵的主模型。

agent/model_metadata.py

为 Provider 的模型添加上下文长度，使 Token 预算、压缩阈值和限制保持合理。

步骤 7：如果 Provider 是原生的，添加适配器和 run_agent.py 支持

如果 Provider 不是普通的 chat completions，将 Provider 特定逻辑隔离在 agent/<provider>_adapter.py 中。

保持 run_agent.py 专注于编排。它应该调用适配器辅助函数，而不是在整个文件中内联手工构建 Provider 负载。

原生 Provider 通常需要在以下位置工作：

新适配器文件

典型职责：

• 构建 SDK/HTTP 客户端
• 解析 Token
• 将 OpenAI 风格的对话消息转换为 Provider 的请求格式
• 如果需要则转换工具 Schema
• 将 Provider 响应规范化回 run_agent.py 期望的格式
• 提取用量和结束原因数据

run_agent.py

搜索 api_mode 并审计每个切换点。至少验证：

• __init__ 选择新的 api_mode
• 客户端构造对 Provider 有效
• _build_api_kwargs() 知道如何格式化请求
• _api_call_with_interrupt() 分发到正确的客户端调用
• 中断/客户端重建路径工作正常
• 响应验证接受 Provider 的格式
• 结束原因提取正确
• Token 用量提取正确
• 回退模型激活可以干净地切换到新 Provider
• 摘要生成和内存刷新路径仍然工作

还要在 run_agent.py 中搜索 self.client.。任何假设标准 OpenAI 客户端存在的代码路径在原生 Provider 使用不同客户端对象或 self.client = None 时可能出错。

提示词缓存和 Provider 特定请求字段

提示词缓存和 Provider 特定旋钮很容易退化。

代码树中已有的示例：

• Anthropic 有原生提示词缓存路径
• OpenRouter 获取 Provider 路由字段
• 不是每个 Provider 都应该接收每个请求端选项

添加原生 Provider 时，仔细检查 Hermes 只发送该 Provider 实际理解的字段。

步骤 8：测试

至少触及保护 Provider 连线的测试。

常见位置：

• tests/test_runtime_provider_resolution.py
• tests/test_cli_provider_resolution.py
• tests/test_cli_model_command.py
• tests/test_setup_model_selection.py
• tests/test_provider_parity.py
• tests/test_run_agent.py
• tests/test_<provider>_adapter.py 用于原生 Provider

对于仅文档的示例，具体文件集可能不同。关键是覆盖：

• 认证解析
• CLI 菜单/Provider 选择
• 运行时 Provider 解析
• Agent 执行路径
• provider:model 解析
• 任何适配器特定的消息转换

禁用 xdist 运行测试：

source venv/bin/activate
python -m pytest tests/test_runtime_provider_resolution.py tests/test_cli_provider_resolution.py tests/test_cli_model_command.py tests/test_setup_model_selection.py -n0 -q

对于更深入的更改，推送前运行完整测试套件：

source venv/bin/activate
python -m pytest tests/ -n0 -q

步骤 9：实际验证

测试后，运行真实冒烟测试。

source venv/bin/activate
python -m hermes_cli.main chat -q "Say hello" --provider your-provider --model your-model

如果你修改了菜单，也测试交互式流程：

source venv/bin/activate
python -m hermes_cli.main model
python -m hermes_cli.main setup

对于原生 Provider，至少验证一次工具调用，不仅仅是纯文本响应。

步骤 10：更新用户文档

如果 Provider 要作为第一方选项发布，也更新用户文档：

• website/docs/getting-started/quickstart.md
• website/docs/user-guide/configuration.md
• website/docs/reference/environment-variables.md

开发者可以完美地连接 Provider，但仍然让用户无法发现所需的环境变量或设置流程。

OpenAI 兼容 Provider 检查清单

当 Provider 是标准 chat completions 时使用此清单。

• 在 hermes_cli/auth.py 中添加了 ProviderConfig
• 在 hermes_cli/auth.py 和 hermes_cli/models.py 中添加了别名
• 在 hermes_cli/models.py 中添加了模型目录
• 在 hermes_cli/runtime_provider.py 中添加了运行时分支
• 在 hermes_cli/main.py 中添加了 CLI 连接（setup.py 自动继承）
• 在 agent/auxiliary_client.py 中添加了辅助模型
• 在 agent/model_metadata.py 中添加了上下文长度
• 更新了运行时/CLI 测试
• 更新了用户文档

原生 Provider 检查清单

当 Provider 需要新协议路径时使用此清单。

• OpenAI 兼容检查清单中的所有内容
• 在 agent/<provider>_adapter.py 中添加了适配器
• 在 run_agent.py 中支持了新 api_mode
• 中断/重建路径正常工作
• 用量和结束原因提取正常工作
• 回退路径正常工作
• 添加了适配器测试
• 实际冒烟测试通过

常见陷阱

1. 添加了 Provider 到 auth 但未添加到模型解析

这会导致凭据正确解析但 /model 和 provider:model 输入失败。

2. 忘记 config["model"] 可以是字符串或字典

很多 Provider 选择代码必须规范化两种形式。

3. 假设必须使用内置 Provider

如果服务只是 OpenAI 兼容的，自定义 Provider 可能已经以更少的维护解决了用户问题。

4. 忘记辅助路径

主聊天路径可以工作，但摘要、内存刷新或视觉辅助可能因为辅助路由从未更新而失败。

5. 原生 Provider 分支隐藏在 run_agent.py 中

搜索 api_mode 和 self.client.。不要假设明显的请求路径是唯一的。

6. 向其他 Provider 发送仅限 OpenRouter 的旋钮

Provider 路由等字段只属于支持它们的 Provider。

7. 更新了 hermes model 但未更新 hermes setup

两个流程都需要知道该 Provider。

实现时的好搜索目标

如果你要查找 Provider 涉及的所有位置，搜索这些符号：

• PROVIDER_REGISTRY
• _PROVIDER_ALIASES
• _PROVIDER_MODELS
• resolve_runtime_provider
• _model_flow_
• select_provider_and_model
• api_mode
• _API_KEY_PROVIDER_AUX_MODELS
• self.client.

相关文档

• Provider 运行时解析
• 架构
• 贡献