Hermes Agent 自定义 API：提供商、传输协议与首次调用检查

Hermes Agent 自定义 Endpoint 以出站方式配置，作为 ~/.hermes/config.yaml 中 providers: 下的命名条目，其中 api 是基础 URL，transport 是线路协议。这与 Hermes 自己的 API 服务器是另一回事，后者的方向相反。搜索结果中两者都被称为“Hermes 自定义 API”，而且各自的官方文档页面会针对相同查询排名——因此首先要确认方向。

本页面介绍的是Nous Research 开源的 Hermes Agent。2026 年 9 月 21 日检查GitHub API时返回了 archived: false、disabled: false、MIT 许可证以及当天的一次推送；最新发布版本是Hermes Agent v0.21.3，于 2026 年 9 月 14 日标记为 v2026.9.14，不是预发布版本。本页面采用的配置来源是该代码仓库和hermes-agent.nousresearch.com。hermes-agent.org 从 nousresearch.com 之外的域名介绍同一项目，并加载 Microsoft Clarity 分析工具（检查于 2026 年 9 月 21 日）；它不是项目自有页面，因此不要从那里获取配置。本页面介绍的也不是 Hermes 3 或 Hermes 4（Nous 的开放权重模型系列），也不是同名的 JavaScript 引擎。

称为 Hermes 自定义 API 的两个相反概念

两行内容均引自 Hermes 自己的页面，阅读日期为 2026 年 9 月 21 日：提供商参考和 API 服务器页面。有一个命名细节值得在你自己的安装中核对：API 服务器页面将 hermes gateway 记录为运行该服务器的命令，而 CLI 参考将 hermes gateway 描述为消息服务管理器，并列出 run、start、stop 和 status 子命令。请运行 hermes gateway --help，不要凭猜测操作。以下内容全部讨论出站部分。

最低限度的出站配置

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com/v1   # aliases accepted: base_url, url
    key_env: KUNAVO_API_KEY          # or inline api_key:, or key_cmd:
    transport: chat_completions      # set it by hand; see the transport section
    models:
      claude-sonnet-5:
        prompt_caching: true

model:
  default: claude-sonnet-5
  provider: custom:kunavo

KUNAVO_API_KEY=your-key

根据提供商参考逐项说明：配置键为 providers.<name>，基础 URL 字段为 api（也接受 base_url 和 url 作为别名），凭据为 key_env，可以是内联的 api_key 或 key_cmd，协议为 transport。同一条配置还接受 name、default_model、models、context_length、discover_models、extra_body、extra_headers、session_affinity_header、ssl_ca_cert / ssl_verify、catalog_provider 和 enabled: false。使用 model.provider: custom:kunavo 选择该条目，或在会话中途使用 /model custom:kunavo:<model-id> 选择。

两个命令不可互换。hermes model 在聊天会话之外运行，是完整的提供商设置向导，也是唯一可以添加提供商或获取密钥的命令。会话内的 /model 只能在现有配置之间切换。对于签发短期令牌的企业端点，key_cmd 是一个会将令牌打印到 stdout 的命令——可以直接输出，也可以通过带有 access_token 字段的 JSON 输出；Hermes 会运行并缓存该令牌，直到临近过期时间，并且它优先于同一条配置上的静态 api_key 或 key_env。

手动选择传输协议，不要将字段留空

提供商参考列出了自定义条目中 transport 可接受的三个值。它还说明，hermes model Custom Endpoint 向导现在会明确询问协议，并将答案持久化到 config.yaml；同时说明，基于 URL 的自动检测“在字段留空时仍会作为回退机制执行”。文档明确说明的唯一检测规则是：/anthropic 路径映射到 anthropic_messages，而 Kunavo 基础 URL 不符合该规则；此处查阅的页面没有枚举其余启发式规则，因此应填写该字段，而不是推断它会如何处理。Kunavo 提供 /v1/chat/completions、/v1/messages 和 /v1/responses，所以从理论上看，每种传输协议都有相匹配的路由。

Anthropic 这一行需要加以限定，而不能给出确定答案。Hermes 的 Azure Foundry 指南说明，由于 Anthropic SDK 会为每个请求追加 /v1/messages，因此会从基础 URL 中移除 /v1；但这句话位于 Azure 标题之下，而提供商参考自身的示例（api: https://proxy.example.com/anthropic）从未说明 Hermes 会为通用代理追加什么后缀。因此，上述两个候选值都有可能正确，其中一个可能会产生带双重 /v1 的 404。请检查第一次调用实际记录的请求路径；基础 URL 文档介绍了这条链路上大多数 404 背后的源站与 /v1 陷阱。身份验证反而是次要问题：Kunavo 的 Messages 路由同时接受 Authorization: Bearer 和 x-api-key，所以 Anthropic SDK 为通用代理发送哪种标头，理论上都应被接受——但 Hermes 没有记录这一选择，因此“应当”才是诚实的措辞。

此页面同样无法回答的一个未决问题。Hermes 记录了 GPT-5.x 系列模型名称会静默升级到 codex_responses，即使 config.yaml 仍为 chat_completions——但这句话出现在 provider: azure-foundry 之下，同时措辞又将其描述为模型名称检测。文档没有说明 provider: custom 上的 GPT slug 是否会触发同样的处理。如果选择 GPT 类模型，请记录第一次调用实际访问了哪个路由。

按传输协议划分，自定义端点不会自动获得的能力

这些都不是套餐限制。根据项目自己的 主页 FAQ，Hermes Agent“基于 MIT 许可证免费且开源”，而 providers: 字典被记录为普通配置，而不是套餐功能。它们是能力限制，并且因通信线路不同而不同。

对于网关，有两个专门的应急选项。catalog_provider 接受 Hermes 提供商 ID 或 models.dev ID，并让该条目的模型继承该目录的元数据——仅用于查询，请求仍会使用你的密钥发送到你的 api URL。discover_models: false 则完全跳过 /models 探测，仅使用你在条目中列出的模型；当发现过程嘈杂或缓慢时，这是修复方法。此处尚未测试 Kunavo 的 /v1/models 响应是否满足 Hermes 的探测要求；如果不满足，上下文检测会回退到 128K 默认值。这些设置背后的成本逻辑——辅助槽位、委派工作线程和缓存连续性——请参阅 Hermes Agent 定价，此处不再重复。

在处理真实工作前执行的验证阶梯

以下是供你执行的步骤，以及应观察到的现象，不是 Kunavo 已获得的结果。 尚未执行任何针对 Kunavo 的 Hermes 运行，没有 Kunavo 针对 Hermes 的设置指南，本页面任何内容都不应被理解为已测试的集成。整个过程中请保留当前工作路由可用。

1. 添加提供商，然后进行诊断。 hermes model 用于添加；文档说明 hermes doctor 用于诊断配置和依赖问题，CLI 参考还记录了它执行的两个自定义端点配置检查——custom_providers 键不是 YAML 列表，以及一个没有匹配 providers: 条目的旧版列表项。两者都只会发出警告，--fix 不会重写它们。
2. 在产生任何费用前确认密钥已加载。 hermes dump 会打印可复制粘贴的设置摘要——版本、提供商、模型以及是否存在 API 密钥。应看到你的模型 ID 和已存在的密钥。hermes prompt-size 离线运行，并报告系统提示和工具架构的字节分解；这是每一轮在任何会话内容之前都会携带的固定部分。
3. 进行一次非流式文本回合。 应收到回复，并确认请求已发送到预期路径。自定义端点虽然“能工作”但返回乱码，是 Hermes 快速入门故障排查表中的一项；该表列出错误的基础 URL、错误的模型名称或实际上不兼容 OpenAI 的端点，并要求先在独立客户端中验证端点。
4. 进行一次流式回合。 应获得增量输出，而不是在末尾一次性获得完整内容。某个端点的流式帧格式是否满足 Hermes 的进度解析要求，本页面未进行测试。
5. 进行一轮工具调用。 应执行该工具。如果调用被打印为文本，则这是服务端的工具调用支持问题，而不是传输协议问题。
6. 读取计量器。 /usage 是会话内的令牌、成本和上下文面板。将其与提供商账户实际记录的费用进行核对——代理根据报告令牌数自行计算的结果只是估算，不是账本。请参阅 使用量文档。

验证阶梯的成本，以及会话中途切换的成本

假设上述六个步骤总共发送 26,000 个输入令牌并接收 1,150 个输出令牌——固定系统提示和工具架构在三次调用中各发送一次，另加一次重新发送的工具结果。该假设仅用于说明；hermes prompt-size 会以字节分解形式报告你自己的固定提示，其准确性高于本页面可以猜测的数字。费率是实时的 Kunavo 目录每百万令牌价格。

这是按目录费率计算的示例性令牌算术，不是实测的 Hermes 任务，也不是账单上限。它不包括缓存写入、外部工具和税费。这个数字的意义在于它很小：验证一条路由的成本，远低于一周后才发现计划任务配置错误的代价。

第二个数字就是 /model 命令隐藏的数字。提示缓存按处理请求的模型建立键，因此任何会话中途的模型变更，都会使下一条消息以完整输入价格重新读取整个会话，而不是使用缓存费率；Hermes 将其描述为便宜约 75% 至 90%。对于一个包含 120,000 个令牌且使用 Claude Sonnet 5 的会话，$1.40 每百万令牌与 $0.14 缓存读取费率之间的差额，在这一轮中约为 $0.151——偶尔一次微不足道，但养成习惯后并非如此。Kunavo 的目录金额是计费下限而非上限：上游报告费用后，账单取目录成本与上游成本乘以适用加价两者中的较高者。最低金额是$10预付充值，无订阅。请参阅 计费。

再次撤销配置

Hermes 记录了撤销路径，因此试用的风险较低。条目上的 enabled: false 会将其隐藏而不会删除。config.yaml 的时间点副本会在 hermes setup 或 hermes migrate 重写它之前写入 backups/config/config.yaml.<reason>.<timestamp>，并且每当它被解析时也会写入；重复内容会跳过，每种原因只保留最新的五份。如果文件之后解析失败，Hermes 会提供最新的有效副本，而不是内置默认值。配置参考还将 model.base_url 标注为“在切换提供商时清除”，因此文档所述的切回内置提供商会删除旧的基础 URL，而不是将其留在文件中——请之后检查实际写入的值，不要想当然。

三个陷阱来自较旧的教程。旧版顶层 custom_providers: 列表仍然有效，hermes update 会自动将它迁移到 providers: 字典中，其中旧版 model 会变为 default_model，旧版 api_mode 会变为 transport。LLM_MODEL 在 .env 中已被彻底移除——config.yaml 是唯一可信来源。此外，两份当前官方页面以两种方式记录 OPENAI_BASE_URL：提供商参考称它仅对 openai-api 提供商生效，而环境变量参考则将其列为自定义端点的基础 URL。该矛盾尚未解决，因此请在 config.yaml 中配置端点，不要依赖该环境变量作为路由。

如果你是在选择提供商，而不是连接提供商，兼容 OpenAI 的 API介绍了兼容接口包含和不包含的内容，Hermes 与 OpenClaw比较了这两个代理。准备好使用已充值的密钥测试这条路由后，请创建 Kunavo 账户。

常见问题

Hermes Agent 文档——提供商参考、API 服务器页面、模型配置页面、配置页面、CLI 参考、斜杠命令参考、快速入门和项目主页——阅读日期为 2026 年 9 月 21 日。当天还通过 GitHub API 核对了仓库状态和最新版本。Kunavo 的三个 API 路由已在其自身源代码中确认。所有美元金额均为基于实时目录费率的示例性令牌算术，不是实测任务成本。Hermes 配置内容来自源文档；尚未执行针对 Kunavo 的 Hermes 运行。