hermes教程-添加提供商

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

提供商特定的认证或令牌刷新
精选的模型目录
设置 / hermes model 菜单条目
用于 provider:model 语法的提供商别名
需要适配器的非 OpenAI API 形状

如果提供商只是“另一个兼容 OpenAI 的基础 URL 和 API 密钥”，那么一个命名的自定义提供商可能就足够了。

心智模型

一个内置提供商需要在多个层面上对齐：

hermes_cli/auth.py 决定如何查找凭据。
hermes_cli/runtime_provider.py 将其转换为运行时数据：
- provider
- api_mode
- base_url
- api_key
- source
run_agent.py 使用 api_mode 来决定如何构建和发送请求。
hermes_cli/models.py 和 hermes_cli/main.py 使提供商在 CLI 中显示。（hermes_cli/setup.py 自动委托给 main.py — 那里不需要更改。）
agent/auxiliary_client.py 和 agent/model_metadata.py 保持辅助任务和令牌预算正常工作。

重要的抽象是 api_mode。

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

首先选择实现路径

路径 A — 兼容 OpenAI 的提供商

当提供商接受标准的聊天补全风格请求时使用此路径。

典型工作：

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

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

路径 B — 原生提供商

当提供商的行为不像 OpenAI 聊天补全时使用此路径。

当前树内示例：

codex_responses
anthropic_messages

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

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

文件清单

每个内置提供商必需的文件

hermes_cli/auth.py
hermes_cli/models.py
hermes_cli/runtime_provider.py
hermes_cli/main.py
agent/auxiliary_client.py
agent/model_metadata.py
测试
website/docs/ 下的面向用户文档

提示

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

原生/非 OpenAI 提供商额外需要的文件

agent/<provider>_adapter.py
run_agent.py
如果提供商 SDK 是必需的，则添加 pyproject.toml

快速路径：简单的 API 密钥提供商

如果你的提供商只是一个使用单个 API 密钥进行身份验证的兼容 OpenAI 的端点，则无需修改 auth.py、runtime_provider.py、main.py 或下面完整清单中的任何其他文件。

你只需要：

在 plugins/model-providers/<your-provider>/ 下创建一个插件目录，包含：
- __init__.py — 在模块级别调用 register_provider(profile)
- plugin.yaml — 清单（名称、kind: model-provider、版本、描述）
仅此而已。提供商插件会在首次调用 get_provider_profile() 或 list_providers() 时自动加载 — 捆绑的插件（此仓库）和位于 $HERMES_HOME/plugins/model-providers/ 的用户插件都会被拾取。

当你添加一个插件并调用 register_provider() 时，以下内容会自动连接：

auth.py 中的 PROVIDER_REGISTRY 条目（凭据解析、环境变量查找）
api_mode 设置为 chat_completions
base_url 从配置或声明的环境变量中获取
按优先级顺序检查 env_vars 以获取 API 密钥
为提供商注册 fallback_models 列表
--provider CLI 标志接受提供商 ID
hermes model 菜单包含该提供商
hermes setup 向导自动委托给 main.py
provider:model 别名语法生效
运行时解析器返回正确的 base_url 和 api_key
--provider <name> CLI 标志接受提供商 ID
回退模型激活可以干净地切换到该提供商

位于 $HERMES_HOME/plugins/model-providers/<name>/ 的用户插件会覆盖同名的捆绑插件（register_provider() 中后写者获胜）— 因此第三方可以在不编辑仓库的情况下修补或替换任何内置配置文件。

请参阅 plugins/model-providers/nvidia/ 或 plugins/model-providers/gmi/ 作为模板，以及完整的模型提供商插件指南以获取字段参考、钩子惯用法和端到端示例。

完整路径：OAuth 和复杂提供商

当你的提供商需要以下任何一项时，使用下面的完整清单：

OAuth 或令牌刷新（Nous Portal、Codex、Google Gemini、Qwen Portal、Copilot）
需要新适配器的非 OpenAI API 形状（Anthropic Messages、Codex Responses）
自定义端点检测或多区域探测（z.ai、Kimi）
精选的静态模型目录或实时 /models 获取
具有特定认证流程的提供商特定 hermes model 菜单条目

步骤 1：选择一个规范的提供商 ID

选择一个提供商 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 在这些文件之间不同，提供商将感觉半连接：认证可能有效，而 /model、设置或运行时解析会静默错过它。

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

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

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

同时向 _PROVIDER_ALIASES 添加别名。

使用现有提供商作为模板：

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

此处需要回答的问题：

Hermes 应检查哪些环境变量，优先级顺序如何？
提供商是否需要基础 URL 覆盖？
是否需要端点探测或令牌刷新？
当凭据缺失时，认证错误应显示什么？

如果提供商需要的不仅仅是“查找 API 密钥”，请添加一个专用的凭据解析器，而不是将逻辑塞入不相关的分支。

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

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

典型的编辑：

_PROVIDER_MODELS
_PROVIDER_LABELS
_PROVIDER_ALIASES
list_available_providers() 中的提供商显示顺序
如果提供商支持实时 /models 获取，则添加 provider_model_ids()

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

此文件还使以下输入生效：

text

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

如果此处缺少别名，提供商可能认证成功，但在 /model 解析中仍然失败。

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

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

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

python

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

如果提供商兼容 OpenAI，api_mode 通常应保持为 chat_completions。

注意 API 密钥优先级。Hermes 已经包含逻辑，以避免将 OpenRouter 密钥泄露给不相关的端点。新提供商应同样明确哪个密钥用于哪个基础 URL。

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

提供商在出现在交互式 hermes model 流程之前是不可发现的。

在 hermes_cli/main.py 中更新以下内容：

provider_labels 字典
select_provider_and_model() 中的 providers 列表
提供商分发（if selected_provider == ...）
--provider 参数选项
如果提供商支持登录/注销流程，则添加相关选项
一个 _model_flow_<provider>() 函数，或者如果适用则重用 _model_flow_api_key_provider()

提示

hermes_cli/setup.py 不需要更改 — 它调用 main.py 中的 select_provider_and_model()，因此你的新提供商会自动出现在 hermes model 和 hermes setup 中。

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

此处涉及两个文件：

`agent/auxiliary_client.py`

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

辅助任务包括：

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

如果提供商没有合理的辅助默认值，辅助任务可能会严重回退，或者意外使用昂贵的主模型。

`agent/model_metadata.py`

为提供商的模型添加上下文长度，以便令牌预算、压缩阈值和限制保持合理。

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

如果提供商不是普通的聊天补全，将提供商特定的逻辑隔离在 agent/<provider>_adapter.py 中。

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

原生提供商通常需要在以下位置工作：

新的适配器文件

典型职责：

构建 SDK / HTTP 客户端
解析令牌
将 OpenAI 风格的对话消息转换为提供商的请求格式
如果需要，转换工具模式
将提供商响应规范化回 run_agent.py 期望的格式
提取用量和完成原因数据

`run_agent.py`

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

__init__ 选择了新的 api_mode
客户端构建对提供商有效
_build_api_kwargs() 知道如何格式化请求
_interruptible_api_call() 分发到正确的客户端调用
中断 / 客户端重建路径有效
响应验证接受提供商的形状
完成原因提取正确
令牌用量提取正确
回退模型激活可以干净地切换到新提供商
摘要生成和内存刷新路径仍然有效

同时搜索 run_agent.py 中的 self.client.。任何假设标准 OpenAI 客户端存在的代码路径，在原生提供商使用不同的客户端对象或 self.client = None 时都可能中断。

提示缓存和提供商特定的请求字段

提示缓存和提供商特定的旋钮很容易退化。

树内已有示例：

Anthropic 有原生提示缓存路径
OpenRouter 获得提供商路由字段
并非每个提供商都应接收每个请求端选项

当你添加原生提供商时，请仔细检查 Hermes 是否只发送该提供商实际理解的字段。

步骤 8：测试

至少，触及保护提供商连接的测试。

常见位置：

tests/hermes_cli/test_runtime_provider_resolution.py
tests/cli/test_cli_provider_resolution.py
tests/hermes_cli/test_model_switch_custom_providers.py（以及相邻的 tests/hermes_cli/test_model_switch_*.py）
tests/hermes_cli/test_setup_model_provider.py
tests/run_agent/test_provider_parity.py
tests/run_agent/test_run_agent.py
对于原生提供商：tests/test_<provider>_adapter.py

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

认证解析
CLI 菜单 / 提供商选择
运行时提供商解析
代理执行路径
provider:model 解析
任何适配器特定的消息转换

使用禁用了 xdist 的测试运行：

bash

source venv/bin/activate
python -m pytest tests/hermes_cli/test_runtime_provider_resolution.py tests/cli/test_cli_provider_resolution.py tests/hermes_cli/test_setup_model_provider.py tests/run_agent/test_provider_parity.py -n0 -q

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

bash

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

步骤 9：实时验证

测试后，运行一个真实的冒烟测试。

bash

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

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

bash

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

对于原生提供商，还要验证至少一次工具调用，而不仅仅是纯文本响应。

步骤 10：更新面向用户的文档

如果提供商打算作为一流选项发布，也更新用户文档：

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

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

兼容 OpenAI 的提供商清单

如果提供商是标准的聊天补全，请使用此清单。

在 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 测试
更新了用户文档

原生提供商清单

当提供商需要新的协议路径时使用此清单。

兼容 OpenAI 清单中的所有内容
在 agent/<provider>_adapter.py 中添加了适配器
在 run_agent.py 中支持新的 api_mode
中断 / 重建路径有效
用量和完成原因提取有效
回退路径有效
添加了适配器测试
实时冒烟测试通过

常见陷阱

1. 将提供商添加到认证但未添加到模型解析

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

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

许多提供商选择代码必须规范化这两种形式。

3. 假设需要内置提供商

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

4. 忘记辅助路径

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

5. 原生提供商分支隐藏在 `run_agent.py` 中

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

6. 将仅 OpenRouter 的旋钮发送给其他提供商

像提供商路由这样的字段只应属于支持它们的提供商。

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

两个流程都需要知道该提供商。

实现时的良好搜索目标

如果你在寻找提供商触及的所有位置，搜索这些符号：

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

字节笔记本

hermes教程-添加提供商

心智模型

首先选择实现路径

路径 A — 兼容 OpenAI 的提供商

路径 B — 原生提供商

文件清单

每个内置提供商必需的文件

原生/非 OpenAI 提供商额外需要的文件

快速路径：简单的 API 密钥提供商

完整路径：OAuth 和复杂提供商

步骤 1：选择一个规范的提供商 ID

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

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

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

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

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

`agent/auxiliary_client.py`

`agent/model_metadata.py`

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

新的适配器文件

`run_agent.py`

提示缓存和提供商特定的请求字段

步骤 8：测试

步骤 9：实时验证

步骤 10：更新面向用户的文档

兼容 OpenAI 的提供商清单

原生提供商清单

常见陷阱

1. 将提供商添加到认证但未添加到模型解析

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

3. 假设需要内置提供商

4. 忘记辅助路径

5. 原生提供商分支隐藏在 `run_agent.py` 中

6. 将仅 OpenRouter 的旋钮发送给其他提供商

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

实现时的良好搜索目标

相关文档

字节笔记本

hermes教程-添加提供商

心智模型

首先选择实现路径

路径 A — 兼容 OpenAI 的提供商

路径 B — 原生提供商

文件清单

每个内置提供商必需的文件

原生/非 OpenAI 提供商额外需要的文件

快速路径：简单的 API 密钥提供商

完整路径：OAuth 和复杂提供商

步骤 1：选择一个规范的提供商 ID

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

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

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

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

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

agent/auxiliary_client.py

agent/model_metadata.py

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

新的适配器文件

run_agent.py

提示缓存和提供商特定的请求字段

步骤 8：测试

步骤 9：实时验证

步骤 10：更新面向用户的文档

兼容 OpenAI 的提供商清单

原生提供商清单

常见陷阱

1. 将提供商添加到认证但未添加到模型解析

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

3. 假设需要内置提供商

4. 忘记辅助路径

5. 原生提供商分支隐藏在 run_agent.py 中

6. 将仅 OpenRouter 的旋钮发送给其他提供商

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

实现时的良好搜索目标

相关文档

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

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

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

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

`agent/auxiliary_client.py`

`agent/model_metadata.py`

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

`run_agent.py`

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

5. 原生提供商分支隐藏在 `run_agent.py` 中

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