Hermes Agent 如何接入 OpenRouter：配置、模型选择与路由

Hermes Agent 是 OpenRouter 上按 token 量计算使用最多的应用，迄今已处理超过 17 万亿个 token。OpenRouter 是人们运行 Hermes Agent 的主要方式之一，因此这套配置成熟、被广泛使用且获得全面支持。

Hermes Agent 是来自 Nous Research 的开源自主智能体，可直接在终端中运行，并且可以搭配你选择的任何模型使用。当你将它连接到 OpenRouter 时，你就能通过一个 API 密钥访问来自 70 多家提供商的 400 多个模型，同时享有自动故障转移和单一账单。

首先需要澄清一点：Hermes Agent 与 Hermes 模型系列（Hermes 3 和 Hermes 4）是 Nous Research 同一生态系统中不同的部分。Hermes Agent 是应用，而 Hermes 3 和 Hermes 4 是它可以运行于其上的语言模型。本指南将解释这一区别，然后带你完成完整的设置和路由配置。

简而言之

• Hermes Agent 是 Nous Research 的开源自主 CLI 智能体。Hermes 3 和 Hermes 4 模型是独立的；该智能体可以运行在两者之一上，也可以通过网关运行在任何模型上。
• 基础设置的默认模型是 ~anthropic/claude-sonnet-latest。openrouter/auto 和 openrouter/pareto-code 是针对特定用例的可选路由模式。
• 大多数配置要求模型至少具有 64K 上下文 token。较小的窗口可能会被拒绝，因为系统提示词加上工具 schema 会将其填满。在选择之前，请在 openrouter.ai/models 查看上下文长度。
• 一个 OpenRouter 密钥就能让该智能体访问来自 70 多家提供商的 400 多个模型，并为受支持的模型提供自动故障转移，因此单个提供商宕机不会中断会话。同一个密钥可用于 任何编码智能体或 AI 工具。
• 路由配置、回退链和辅助模型卸载位于 ~/.hermes/config.yaml。标题生成和视觉等侧任务可以运行在比主循环更便宜的模型上。
• 运行该智能体是免费的（采用 MIT 许可证）；你只需为其消耗的模型 token 付费。当前计费详情请参见 openrouter.ai/pricing。

什么是 Hermes Agent？（以及它不是什么）

围绕 Hermes 的许多混淆源于这样一个事实：Nous Research 既创建了一个智能体，也创建了一个同名的语言模型系列。Hermes Agent 是一个命令行应用，而 Hermes 3 和 Hermes 4 是可以作为该智能体后端的语言模型。

当人们搜索“Hermes 3”、“Hermes 4”或“Hermes 4 405B”时，他们通常是在找这些语言模型。Hermes Agent 是应用，而 Hermes 3 和 Hermes 4 是可用作其后端的模型。

智能体与模型：区分说明

Hermes Agent 实际能做什么

Hermes Agent 内置 40 多个工具，用于网页搜索、浏览器自动化和图像理解等任务。它还包含一个消息网关，可连接到 20 多个平台，包括 Telegram、Discord、Slack、WhatsApp、Signal 和 Matrix。

它与典型聊天界面的不同之处在于其持久记忆系统。它可以跨会话记住信息，因此你不必每次开始新对话时都重复项目细节或上下文。

该代理在运行位置上也很灵活。你可以将其部署在本地机器上，也可以使用 Docker、SSH、Daytona、Modal 和 Singularity 等环境。

为什么要将 Hermes Agent 与 OpenRouter 搭配使用？

如果你曾经使用过多个 AI 提供商，你就知道事情会变得多快就一团糟。每个提供商都有自己的账户、API 密钥、计费设置和模型目录。OpenRouter 让你通过一个 API 密钥和计费账户即可访问来自 70 多个提供商的 400 多个模型。

OpenRouter 已经是 Hermes Agent 最受欢迎的后端。截至 2026 年 6 月，Hermes Agent 在 OpenRouter 的 应用排名中按总 token 使用量位列第一，处理了超过 17 万亿个 token。该集成被广泛使用、经过充分测试，并已在大规模场景中得到验证。

你可以通过更改一个字符串来切换模型。代理所做的一切都通过你在 openrouter.ai/activity 的使用视图集中跟踪。

OpenRouter 会自动在提供商之间进行负载均衡，并在提供商返回 5xx 错误或触及速率限制时切换，因此当某个提供商宕机时，长时间运行的代理任务不会中断。失败请求的计费行为由 零完成保险覆盖。

设置：将 Hermes Agent 连接到 OpenRouter

如果你还没有安装 Hermes，请从以下命令开始：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

它适用于 Linux、macOS、WSL2 和 Termux。通过原生 PowerShell 的 Windows 支持仍处于早期测试阶段。

安装完成后，将 Hermes Agent 连接到 OpenRouter 只需 2 个步骤：创建 API 密钥，然后配置 Hermes 使用它。配置完成后，Hermes Agent 会通过 OpenRouter 进行身份验证，并使用你在配置中指定的模型 slug 执行所有任务。

上下文长度是一个硬性约束。大多数设置至少需要 64K token 的上下文，如果窗口更小，代理可能会拒绝启动。

在任何对话开始之前，系统提示和工具 schema 已经消耗了上下文窗口的很大一部分。你可以在 openrouter.ai/models 查看任何模型支持的上下文大小。

推荐：交互式设置

OpenRouter cookbook 建议从交互式模型选择器开始：

hermes model

这会引导你选择提供商并配置模型。Hermes CLI 仍在积极演进中，因此请参考最新的集成 cookbook 以了解确切流程；交互步骤可能会因版本而异。

选择模型时，请确保它至少有 64K 上下文。推荐的起始选项通常是 ~anthropic/claude-sonnet-latest。你可以在 openrouter.ai/models 按上下文长度筛选模型，以便在继续之前确认。

成功的设置很容易识别。运行 hermes chat 后，你应该会看到 Hermes Agent 提示符显示你连接的提供商和所选模型。

如果出现 401 错误或“provider not found”提示，通常意味着 API 密钥没有正确保存，或者 provider 名称有拼写错误。重新运行设置命令通常就能解决。

快捷方式：直接配置路径

如果你想跳过交互式设置，直接保存 API 密钥并立即开始聊天：

hermes config set OPENROUTER_API_KEY sk-or-...
hermes chat --provider openrouter --model '~anthropic/claude-sonnet-latest'

将 sk-or-... 替换为你实际的 OpenRouter API 密钥。这会保存密钥并使用 ~anthropic/claude-sonnet-latest 别名启动聊天。~ 前缀告诉 OpenRouter 解析到该系列中的最新模型。

当你以编程方式配置 agent 并希望避免交互式设置流程时，这种方法很有用。

手动配置（高级）

密钥存储在 ~/.hermes/.env 中，而模型和 provider 设置位于 ~/.hermes/config.yaml 中。压缩、辅助模型以及其他高级选项等功能直接在 config.yaml 中配置。

将你的 API 密钥添加到 ~/.hermes/.env，并从环境变量或密钥管理器中加载它。不要将其提交到版本控制中：

OPENROUTER_API_KEY=<your-api-key>

将模型和 provider 放入 ~/.hermes/config.yaml：

model:
  provider: openrouter
  default: ~anthropic/claude-sonnet-latest

当你对配置进行版本控制或以编程方式启动 agent 时，这种方法很方便。

选择模型

为 Hermes Agent 选择模型时，最重要的要求是上下文长度。大多数配置需要至少 64K tokens 才能正常运行。

上下文窗口较小的模型通常无法启动，因此在选择模型之前，请前往 openrouter.ai/models，按上下文长度筛选，并确保你的选择支持至少 64K tokens。

模型 ID 的工作原理

OpenRouter 模型 ID 使用 provider/model-name 格式。~ 前缀是一种路由快捷方式：它告诉 OpenRouter 自动解析到某个模型系列的最新可用版本，而不是将你锁定在特定版本上。

你可以在 models 页面 浏览完整目录，并按上下文长度、价格和功能进行筛选。对于本指南中的工作流，低于 64K 的模型不太可能运行。

当你不想选择时的自动路由

openrouter/auto 是一种可选的路由模式。它会根据 OpenRouter 社区在过去 7 天窗口内对这类任务的总体支出，自动为每个请求挑选一个强大的模型。如果你没有偏好的模型，只想在不做任何基准测试的情况下获得可靠结果，这是一个很好的起点。

当你需要更多控制时，下面的路由部分提供了更细粒度的选项。

Provider 路由、回退与辅助模型

一旦 Hermes Agent 连接成功，~/.hermes/config.yaml 中的路由就决定了成本、可靠性以及如何处理故障。

该文件中的 3 个主要控制项（provider 路由、回退链和辅助模型卸载）相互独立，因此你可以混合搭配使用。

概括来说：模型选择决定哪个任务发送给哪个模型；provider_routing 决定哪个 provider 实际执行请求；如果该 provider 失败，fallback_providers 会接管并重新路由请求，而不会中断会话或丢失上下文。

Provider 路由控制

provider_routing 部分控制由哪个 provider 处理每个请求：

将 data_collection: deny 设置为防止你的提示词被提供商记录。其他允许的值请参阅提供商路由文档。

:nitro 和 :floor 后缀是 sort 设置的请求级快捷方式。:nitro 映射到 sort: throughput，为该特定请求优先考虑速度，而 :floor 映射到 sort: price，选择最便宜的可用提供商。这些仅覆盖该单次调用的 provider_routing，当你想要临时更改行为而不编辑配置文件时非常有用。

回退链

当主模型失败时，fallback_providers 设置会生效。每个条目是一个提供商和模型的配对；当其中一个触发时，Hermes 会在会话中途切换到它，而不会丢失你的对话。

fallback_providers:
  - provider: openrouter
    model: ~anthropic/claude-sonnet-latest
  - provider: openrouter
    model: ~google/gemini-flash-latest

如果主模型出错，请求会路由到下一个条目，Hermes Agent 会保持其记忆和上下文完整。对于一个运行数小时的 agent 来说，这就是短暂的提供商故障和会话死亡之间的区别。

辅助模型

辅助模型处理诸如生成标题、处理视觉请求和执行压缩等侧任务。这能让你的主模型专注于实际的推理和编码任务。

auxiliary:
  title:
    provider: openrouter
    model: ~google/gemini-flash-latest
  vision:
    provider: openrouter
    model: ~google/gemini-flash-latest
  compression:
    provider: openrouter
    model: ~google/gemini-flash-latest

对于生成对话标题等简单任务，没有理由使用像 Claude Sonnet 这样的高成本模型。将这些任务卸载到更便宜的模型，例如 Gemini Flash，可以降低成本，同时保持主工作流程不变。

一个很好的经验法则：将辅助任务指向你为每项工作所信任的最便宜的模型。

使用 Pareto Code 路由器降低成本

如果你想在不手动测试和比较模型的情况下控制成本，openrouter/pareto-code 让 OpenRouter 自动选择仍满足最低质量门槛的最便宜的模型：

model:
  provider: openrouter
  model: openrouter/pareto-code

openrouter:
  min_coding_score: 0.65

启用此功能后，OpenRouter 会为每个编码任务选择满足你所选阈值的最低成本模型。该集成会自动处理请求格式，因此你无需自己管理路由逻辑。

编码分数范围从 0.0 到 1.0，值越高意味着模型越强大但也越昂贵。一个好的起点是 0.65：

• 对于速度与成本比精度更重要的日常编辑，降低它
• 对于正确性比节省 token 更重要的复杂重构，提高它

叠加廉价选项

openrouter/pareto-code 控制主编码循环，而 auxiliary 处理标题、视觉和压缩等侧任务。它们协同工作，你也可以将它们与 :floor 路由结合使用，以进一步节省成本。

OpenRouter 还在多个提供商中提供超过 25 个免费模型。如果你选择一个具有 64K+ 上下文的免费模型，你可以为业余使用运行低成本甚至零成本设置，同时将 Pareto 路由保留给真正需要更高质量模型的任务。在 openrouter.ai/pricing 查看当前定价和免费层可用性。

监控使用情况和故障排除

agent 使用的所有内容都通过单个 API 密钥，这意味着所有活动都在一个地方可见。你可以在 openrouter.ai/activity 跟踪所有 Hermes Agent 会话的请求、成本和 token 使用情况，并可按模型和时间范围进行筛选。

常见错误和修复

大多数设置问题分为 2 类：

1. 如果 Hermes 完全找不到你的 API 密钥，问题出在本地。这通常意味着密钥从未保存到 ~/.hermes/.env。
2. 如果密钥存在但身份验证仍然失败，问题出在账户端。密钥可能无效、已过期，或者你的 OpenRouter 账户可能没有剩余额度。

如果某个模型在其他配置中可用，但在 Hermes Agent 中拒绝启动，通常是 64K 上下文要求所致，而非配置错误。请换用其他模型，而不是调试 YAML。

如果你正在探索其他终端原生 agent，OpenRouter 还为 OpenClaw 提供了 cookbook 集成，这是一个使用相同后端的多平台聊天 agent。

常见问题

Hermes Agent 与 Hermes 3 / Hermes 4 模型是同一个吗？

不是。Hermes Agent 是 Nous Research 开发的开源自主 CLI 应用；Hermes 3 和 Hermes 4 是同一团队推出的独立模型系列。你可以通过 OpenRouter 使用 Hermes 模型或任何模型作为后端来运行 Hermes Agent。

Hermes Agent 免费吗？

该 agent 是开源的（MIT），可免费运行。你只需为通过提供商使用的模型 token 付费。当前费率（包括免费层模型）请见 openrouter.ai/pricing。

在 OpenRouter 上应该为 Hermes Agent 使用什么模型？

从 ~anthropic/claude-sonnet-latest 开始：它是基础设置中记录的默认模型，并满足 64K 上下文要求。运行起来后，openrouter/auto 会自动路由到强大的模型，无需你选择，而 openrouter/pareto-code 专门针对编码任务优化成本。

我需要单独的提供商账户吗？

对于大多数受支持的模型，不需要。一个 OpenRouter 密钥即可让 Hermes Agent 访问来自 70 多家提供商的 400 多个模型，并具备自动故障转移。

如果你在某个特定模型上遇到访问错误，请查看该模型在 openrouter.ai/models 上的页面；某些模型需要提供商特定的资格。大多数情况下，切换到其他模型即可解决问题。

为什么 Hermes Agent 在启动时拒绝我的模型？

大多数配置要求至少 64K 上下文 token；较小的窗口可能无法容纳系统提示词和工具 schema。请切换到上下文更大的模型。可在 openrouter.ai/models 按上下文长度筛选以寻找候选模型。

提供商定价没有加价。当前平台费用和计费详情（包括如何处理失败请求）请见 openrouter.ai/pricing。