Hermes Agent 是 OpenRouter 上按 token 用量计算使用最多的应用，迄今已处理超过 17 万亿 token。OpenRouter 是人们运行 Hermes Agent 的主要方式之一，因此这套配置成熟、被广泛使用，并得到全面支持。
Hermes Agent 是来自 Nous Research 的开源自主智能体，可直接在终端中运行，并且能与你选择的任何模型配合使用。当你将它连接到 OpenRouter 时，你就能通过一个 API key 访问来自 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+ 模型，并对受支持的模型自动进行故障转移，因此单个提供商宕机不会中断会话。
- 路由配置、回退链以及辅助模型卸载都放在
~/.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 3 / Hermes 4 | |
|---|---|---|
| 它是什么 | 自主 CLI 智能体（一个应用） | 语言模型（大脑） |
| 开发者 | Nous Research | Nous Research |
| 运行方式 | 安装 CLI，并将其指向某个模型 | 通过提供商以模型 ID 的形式调用 |
| 许可证 | 开源（MIT） | Nous Research 模型权重遵循其各自的条款 |
| 关系 | 需要一个模型来进行思考 | 可以作为 Hermes Agent 所运行的模型后端 |
Hermes Agent 实际能做什么
Hermes Agent 内置 40 多种工具，可用于网页搜索、浏览器自动化和图像理解等任务。它还包含一个消息网关，可连接 20 多个平台，包括 Telegram、Discord、Slack、WhatsApp、Signal 和 Matrix。
它与典型聊天界面的不同之处在于其持久记忆系统。它可以跨会话记住信息，因此你不必每次开始新对话时都反复说明项目细节或上下文。
该智能体在运行位置上也很灵活。你可以将其部署在本地机器上，也可以使用 Docker、SSH、Daytona、Modal 和 Singularity 等环境。
为什么通过 OpenRouter 运行 Hermes Agent？
如果你曾经使用过多个 AI 提供商，就会知道事情很快就会变得混乱。每个提供商都有自己的账户、API key、计费设置和模型目录。OpenRouter 让你通过单个 API key 和计费账户，即可访问来自 70 多个提供商的 400 多个模型。
OpenRouter 已经是 Hermes Agent 最受欢迎的后端。截至 2026 年 6 月，Hermes Agent 按总 token 使用量在 OpenRouter 的 应用排名中位列第一，已处理超过 17 万亿 token。该集成被广泛使用、经过充分测试，并已在大规模场景中得到验证。
| 不使用网关 | 使用 OpenRouter |
|---|---|
| 每个提供商一个账户、密钥和账单 | 一个密钥即可访问 70+ 提供商的 400+ 模型 |
| 当提供商返回 5xx 错误或触发速率限制时手动重试 | 自动故障转移，会话中途切换，无需运维工作 |
| 在某些提供商处，失败的调用仍需付费 | 失败的请求不计费 |
| 每个提供商仪表盘各自独立的用量视图 | 一个活动仪表盘，覆盖所有模型 |
| 提供商标价加上你自己的加价计算 | 无加价；目录价加上平台费 |
你只需更改一个字符串即可在不同模型之间切换。智能体所做的一切都通过你在 openrouter.ai/activity 的用量视图集中追踪。
OpenRouter 会自动在各提供商之间进行负载均衡，并在某个提供商返回 5xx 错误或触发速率限制时切换过去，因此长时间运行的智能体任务不会因某个提供商宕机而中断。失败请求的计费行为由 zero-completion insurance 覆盖。
设置：将 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 key，然后配置 Hermes 使用它。配置完成后，Hermes Agent 会通过 OpenRouter 进行身份验证，并对所有任务使用你在配置中指定的模型 slug。
上下文长度是一项硬性约束。大多数配置至少需要 64K tokens 的上下文，如果窗口更小，该智能体可能会拒绝启动。
在任何对话开始之前，系统提示词和工具 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 key 没有正确保存，或者提供商名称中有拼写错误。重新运行配置命令通常就能解决。
快捷方式：直接配置路径
如果你希望跳过交互式配置，保存你的 API key 并立即开始对话：
hermes config set OPENROUTER_API_KEY sk-or-...
hermes chat --provider openrouter --model '~anthropic/claude-sonnet-latest'将 sk-or-... 替换为你实际的 OpenRouter API key。这会保存该 key 并使用 ~anthropic/claude-sonnet-latest 别名开始对话。~ 前缀会告诉 OpenRouter 解析到该系列中的最新模型。
当你以编程方式配置智能体并希望避免交互式配置流程时，这种方法很有用。
手动配置（高级）
密钥存储在 ~/.hermes/.env 中，而模型和提供商设置位于 ~/.hermes/config.yaml 中。压缩、辅助模型以及其他高级选项等功能直接在 config.yaml 中配置。
将你的 API key 添加到 ~/.hermes/.env，并从环境变量或密钥管理器中加载它。不要将其提交到版本控制中：
OPENROUTER_API_KEY=<your-api-key>将模型和提供商放入 ~/.hermes/config.yaml：
model:
provider: openrouter
default: ~anthropic/claude-sonnet-latest当你对某个配置进行版本控制或以编程方式启动智能体时，这种方法非常方便。
选择模型
为 Hermes Agent 选择模型时，最重要的要求是上下文长度。大多数配置至少需要 64K tokens 才能正常运行。
上下文窗口较小的模型往往无法启动，因此在选择模型之前，请前往 openrouter.ai/models，按上下文长度筛选，并确保你的选择至少支持 64K tokens。
模型 ID 的工作原理
OpenRouter 模型 ID 使用 provider/model-name 格式。~ 前缀是一个路由快捷方式：它告诉 OpenRouter 自动解析到某个模型系列的最新可用版本，而不是将你锁定在某个特定发布版本上。
| 模型 ID | 解析结果 |
|---|---|
~anthropic/claude-sonnet-latest | 最新的 Claude Sonnet 别名（基础配置的默认值） |
~google/gemini-flash-latest | 最新的 Gemini Flash 别名（便宜、快速，适合辅助任务） |
deepseek/deepseek-v4-flash | DeepSeek 的快速对话模型（性价比极高） |
openrouter/auto | 在整个模型目录中自动路由（由 NotDiamond 提供支持） |
你可以在 models 页面 浏览完整目录，并按上下文长度、价格和功能进行筛选。对于本指南中的工作流，任何低于 64K 的模型都不太可能运行。
当你不想做选择时，使用自动路由
openrouter/auto 是一种可选的路由模式。它会根据 NotDiamond 的路由决策，为每个请求自动挑选一个强大的模型。如果你没有偏好的模型，只想获得可靠的结果而不做任何基准测试，这是一个很好的起点。
当你需要更多控制时，下面的路由部分提供了更细粒度的选项。
提供商路由、回退与辅助模型
一旦 Hermes Agent 连接成功，~/.hermes/config.yaml 中的路由将决定成本、可靠性以及故障处理方式。
该文件中的 3 个主要控制项（提供商路由、回退链和辅助模型卸载）相互独立，因此你可以自由组合搭配。
从高层来看：模型选择决定哪个任务发送给哪个模型；provider_routing 决定实际由哪个提供商执行请求；而如果该提供商失败，fallback_providers 会接管并重新路由请求，而不会中断会话或丢失上下文。
提供商路由控制
provider_routing 部分控制由哪个提供商处理每个请求：
| 字段 | 它控制什么 | 示例值 |
|---|---|---|
sort | 优化维度 | throughput、price、latency |
only | 提供商允许列表 | [anthropic] |
ignore | 提供商阻止列表 | [novita] |
order | 显式提供商优先级 | [anthropic, google] |
data_collection | 提供商是否可以记录提示词 | deny |
设置 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 的记忆和上下文保持完好。对于一个运行数小时的智能体来说，这就是一次短暂的提供商故障与一个彻底死掉的会话之间的区别。
辅助模型
辅助模型负责处理生成标题、处理视觉请求以及执行压缩等侧边任务。这能让你的主模型专注于实际的推理和编码任务。
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 查看当前定价和免费额度可用情况。
监控用量与故障排查
智能体使用的一切都通过单个 API key，这意味着所有活动都能在一处可见。你可以在 openrouter.ai/activity 跟踪所有 Hermes Agent 会话的请求、成本和 token 用量，并按模型和时间范围进行筛选。
常见错误与修复方法
大多数配置问题分为 2 类：
- 如果 Hermes 完全找不到你的 API key，问题出在本地。这通常意味着该 key 从未保存到
~/.hermes/.env。 - 如果 key 存在但认证仍然失败，问题出在账户侧。该 key 可能无效、已过期，或者你的 OpenRouter 账户已无剩余额度。
| 问题 | 修复方法 |
|---|---|
| “No API key” / 未找到提供商 | 验证 ~/.hermes/.env 中是否有该 key，或重新运行配置命令 |
| 401 / 403 错误 | 在 openrouter.ai/keys 检查密钥有效性，并确认你的额度余额 |
| 模型无响应 | 验证 ~/.hermes/config.yaml 中的模型 ID 是否与 provider/model-name 在 openrouter.ai/models 上的有效模型匹配 |
| 启动时的上下文错误 | 切换到上下文至少为 64K 的 OpenRouter 模型 |
如果某个模型在其他配置下能正常工作，但在 Hermes Agent 中却无法启动，那通常是 64K 上下文要求导致的，而不是配置错误。此时应换用其他模型，而不是去调试 YAML。
如果你正在探索其他终端原生智能体，OpenRouter 还为 OpenClaw 提供了 cookbook 集成，这是一个使用相同后端的多平台聊天智能体。
常见问题
Hermes Agent 和 Hermes 3 / Hermes 4 模型是同一个东西吗？
不是。Hermes Agent 是 Nous Research 推出的开源自主 CLI 应用；Hermes 3 和 Hermes 4 是同一团队开发的独立模型系列。你可以通过 OpenRouter，用 Hermes 模型或任何其他模型作为后端来运行 Hermes Agent。
Hermes 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 运行 Hermes Agent 会额外收费吗？
提供商定价没有加价。请查看 openrouter.ai/pricing 了解当前的平台费用和计费详情，包括失败请求的处理方式。
Hermes Agent is OpenRouter’s most-used application by token volume, having processed more than 17 trillion tokens so far. OpenRouter is one of the primary ways people run Hermes Agent, so the setup is mature, widely used, and fully supported.
Hermes Agent is an open-source autonomous agent from Nous Research that runs directly in the terminal, and it can work with any model you choose. When you connect it to OpenRouter, you get access to more than 400 models from over 70 providers, along with automatic failover and a single bill, all through one API key.
One thing to clear up before anything else: Hermes Agent and the Hermes model family (Hermes 3 and Hermes 4) are different parts of the same ecosystem from Nous Research. Hermes Agent is the application, while Hermes 3 and Hermes 4 are language models it can run on. This guide explains the distinction and then walks through the complete setup and routing configuration.
Tl;dr
- Hermes Agent is Nous Research’s open-source autonomous CLI agent. The Hermes 3 and Hermes 4 models are separate; the agent can run on either, or on any model via a gateway.
- The default model for basic setup is
~anthropic/claude-sonnet-latest.openrouter/autoandopenrouter/pareto-codeare optional routing modes for specific use cases. - Most configurations require a model with at least 64K context tokens. Smaller windows may be rejected because the system prompt plus tool schemas fill them. Check context length at openrouter.ai/models before choosing.
- One OpenRouter key gives the agent access to 400+ models from 70+ providers with automatic failover for supported models, so a single provider outage doesn’t stop a session.
- Routing config, fallback chains, and auxiliary-model offloading live in
~/.hermes/config.yaml. Side tasks like titling and vision can run on cheaper models than the main loop. - Running the agent is free (it’s MIT-licensed); you pay only for the model tokens it spends. See openrouter.ai/pricing for current billing details.
What Is Hermes Agent? (And What It Isn’t)
Much of the confusion around Hermes stems from the fact that Nous Research created both an agent and a family of language models that share the same name. Hermes Agent is a command-line application, while Hermes 3 and Hermes 4 are language models that can serve as the agent’s backend.
When people search for “Hermes 3”, “Hermes 4”, or “Hermes 4 405B”, they’re usually looking for the language models. Hermes Agent is the application, and Hermes 3 and Hermes 4 are models that can be used as backends for it.
Agent vs model: the disambiguation
| Hermes Agent | Hermes 3 / Hermes 4 | |
|---|---|---|
| What it is | Autonomous CLI agent (an application) | Language models (the brains) |
| Maker | Nous Research | Nous Research |
| You run it by | Installing the CLI, pointing it at a model | Calling it as a model ID through a provider |
| License | Open-source (MIT) | Nous Research model weights under their own terms |
| Relationship | Needs a model to think | Can be a model backend that Hermes Agent runs on |
What Hermes Agent actually does
Hermes Agent comes with more than 40 built-in tools for tasks like web search, browser automation, and image understanding. It also includes a messaging gateway that connects to over 20 platforms, including Telegram, Discord, Slack, WhatsApp, Signal, and Matrix.
What sets it apart from a typical chat interface is its persistent memory system. It can remember information across sessions, so you don’t have to keep repeating project details or context every time you start a new conversation.
The agent is also flexible about where it runs. You can deploy it locally on your machine or use environments such as Docker, SSH, Daytona, Modal, and Singularity.
Why run Hermes Agent with OpenRouter?
If you’ve ever worked with multiple AI providers, you know how quickly things get messy. Every provider has its own account, API key, billing setup, and model catalog. OpenRouter gives you access to more than 400 models from over 70 providers through a single API key and billing account.
OpenRouter is already the most popular backend for Hermes Agent. As of June 2026, Hermes Agent ranks first on OpenRouter’s app rankings by total token usage, with more than 17 trillion tokens processed. The integration is widely used, well-tested, and proven at scale.
| Without a gateway | With OpenRouter |
|---|---|
| One account, key, and bill per provider | One key for 400+ models across 70+ providers |
| Manual retry when a provider 5xxs or rate-limits | Automatic failover, mid-session, no ops work |
| Pay for failed calls on some providers | Failed requests aren’t billed |
| Separate usage view per provider dashboard | One activity dashboard across every model |
| Provider list price plus your own markup math | No markup; catalog price plus a platform fee |
You can switch between models by changing a single string. Everything the agent does is tracked in one place through your usage view at openrouter.ai/activity.
OpenRouter automatically load balances across providers and switches over if a provider returns 5xx errors or hits rate limits, so long-running agent tasks aren’t interrupted when a provider goes down. Billing behavior for failed requests is covered by zero-completion insurance.
Setup: Connect Hermes Agent to OpenRouter
If you haven’t installed Hermes yet, start with:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashIt works on Linux, macOS, WSL2, and Termux. Windows support through native PowerShell is still in early beta.
Once installed, connecting Hermes Agent to OpenRouter takes 2 steps: create an API key, then configure Hermes to use it. Once configured, Hermes Agent authenticates with OpenRouter and uses the model slug you specify in your config for all tasks.
Context length is a hard constraint. Most setups require at least 64K tokens of context, and the agent may refuse to start with smaller windows.
The system prompt and tool schemas already consume a significant portion of the context window before any conversation begins. You can check supported context sizes for any model at openrouter.ai/models.
Recommended: interactive setup
The OpenRouter cookbook recommends starting with the interactive model picker:
hermes modelThis walks you through selecting a provider and configuring your model. The Hermes CLI is still actively evolving, so refer to the latest integration cookbook for the exact flow; the interactive steps can change between versions.
When choosing a model, make sure it has at least 64K context. The recommended starting option is typically ~anthropic/claude-sonnet-latest. You can filter models by context length at openrouter.ai/models to confirm before you proceed.
A successful setup is easy to recognize. After running hermes chat, you should see the Hermes Agent prompt showing your connected provider and selected model.
If you get a 401 error or a “provider not found” message, it usually means the API key wasn’t saved correctly, or there’s a typo in the provider name. Rerunning the setup command normally fixes it.
Quick: the direct config path
If you prefer to skip the interactive setup, save your API key and start a chat immediately:
hermes config set OPENROUTER_API_KEY sk-or-...
hermes chat --provider openrouter --model '~anthropic/claude-sonnet-latest'Replace sk-or-... with your actual OpenRouter API key. This saves the key and starts a chat using the ~anthropic/claude-sonnet-latest alias. The ~ prefix tells OpenRouter to resolve to the latest model in that family.
This approach is useful when provisioning agents programmatically and you want to avoid an interactive setup flow.
Manual config (advanced)
Secrets are stored in ~/.hermes/.env, while model and provider settings live in ~/.hermes/config.yaml. Features such as compression, auxiliary models, and other advanced options are configured directly in config.yaml.
Add your API key to ~/.hermes/.env and load it from your environment or a secrets manager. Don’t commit it to version control:
OPENROUTER_API_KEY=<your-api-key>Put the model and provider in ~/.hermes/config.yaml:
model:
provider: openrouter
default: ~anthropic/claude-sonnet-latestThis approach is handy when you’re version-controlling a setup or spinning up agents programmatically.
Choosing a Model
The most important requirement when choosing a model for Hermes Agent is context length. Most configurations need at least 64K tokens to run properly.
Models with smaller context windows often fail to start, so before selecting a model, go to openrouter.ai/models, filter by context length, and make sure your choice supports at least 64K tokens.
How model IDs work
OpenRouter model IDs use a provider/model-name format. The ~ prefix is a routing shortcut: it tells OpenRouter to automatically resolve to the latest available version of a model family, rather than lock you to a specific release.
| Model ID | What it resolves to |
|---|---|
~anthropic/claude-sonnet-latest | Latest Claude Sonnet alias (the default for basic setup) |
~google/gemini-flash-latest | Latest Gemini Flash alias (cheap, fast, good for side tasks) |
deepseek/deepseek-v4-flash | DeepSeek’s fast chat model (strong value) |
openrouter/auto | Auto-routing across the catalog (powered by NotDiamond) |
You can browse the full catalog on the models page and filter by context length, price, and capabilities. For the workflows in this guide, anything under 64K is unlikely to run.
Auto-routing when you don’t want to choose
openrouter/auto is an optional routing mode. It automatically picks a strong model for each request based on NotDiamond’s routing decisions. It’s a good starting point if you don’t have a preferred model and just want reliable results without doing any benchmarking.
When you need more control, the routing section below offers finer-grained options.
Provider Routing, Fallbacks & Auxiliary Models
Once Hermes Agent is connected, routing in ~/.hermes/config.yaml determines cost, reliability, and how failures are handled.
The 3 main controls in this file (provider routing, fallback chains, and auxiliary model offloading) are independent, so you can mix and match them.
At a high level: model selection decides which task is sent to which model; provider_routing decides which provider actually executes the request; and if that provider fails, fallback_providers take over and reroute the request without breaking the session or losing context.
Provider routing controls
The provider_routing section controls which provider handles each request:
| Field | What it controls | Example value |
|---|---|---|
sort | Optimization axis | throughput, price, latency |
only | Allowlist of providers | [anthropic] |
ignore | Blocklist of providers | [novita] |
order | Explicit provider priority | [anthropic, google] |
data_collection | Whether prompts can be logged by providers | deny |
Set data_collection: deny to prevent your prompts from being logged by providers. The provider routing documentation covers the other allowed values.
The :nitro and :floor suffixes are request-level shortcuts for the sort setting. :nitro maps to sort: throughput, prioritizing speed for that specific request, while :floor maps to sort: price, choosing the cheapest available provider. These override provider_routing for that single call only, which is useful when you want temporary behavior changes without editing your config file.
Fallback chains
The fallback_providers setting kicks in when the primary model fails. Each entry is a provider-and-model pair; when one fires, Hermes swaps to it mid-session without losing your conversation.
fallback_providers:
- provider: openrouter
model: ~anthropic/claude-sonnet-latest
- provider: openrouter
model: ~google/gemini-flash-latestIf the primary errors out, the request routes to the next entry and Hermes Agent keeps its memory and context intact. For an agent that runs for hours, this is the difference between a transient provider blip and a dead session.
Auxiliary models
Auxiliary models handle side tasks such as generating titles, handling vision requests, and performing compression. This keeps your main model focused on the actual reasoning and coding tasks.
auxiliary:
title:
provider: openrouter
model: ~google/gemini-flash-latest
vision:
provider: openrouter
model: ~google/gemini-flash-latest
compression:
provider: openrouter
model: ~google/gemini-flash-latestThere’s no reason to use a high-cost model like Claude Sonnet for simple tasks such as generating a conversation title. Offloading these to a cheaper model, such as Gemini Flash, cuts costs while keeping the main workflow unchanged.
A good rule of thumb: point the auxiliary tasks at the cheapest model you trust for each job.
Cutting costs with the Pareto Code router
If you want cost control without manually testing and comparing models, openrouter/pareto-code lets OpenRouter automatically choose the cheapest model that still meets a minimum quality bar:
model:
provider: openrouter
model: openrouter/pareto-code
openrouter:
min_coding_score: 0.65With this enabled, OpenRouter selects the lowest-cost model that meets your chosen threshold for each coding task. The integration handles the request formatting automatically, so you don’t need to manage routing logic yourself.
The coding score ranges from 0.0 to 1.0, where higher values mean stronger but more expensive models. A good starting point is 0.65:
- Lower it for routine edits where speed and cost matter more than precision
- Raise it for complex refactors where correctness is more important than saving tokens
Stacking the cheap options
openrouter/pareto-code controls the main coding loop, while auxiliary handles side tasks like titles, vision, and compression. These work together, and you can also combine them with :floor routing for additional cost savings.
OpenRouter also provides more than 25 free models across several providers. If you pick a free model with 64K+ context, you can run a low-cost or even zero-cost setup for hobby use, while reserving Pareto routing for tasks that actually need higher-quality models. Check current pricing and free-tier availability at openrouter.ai/pricing.
Monitoring Usage & Troubleshooting
Everything the agent uses goes through a single API key, which means all activity is visible in one place. You can track requests, costs, and token usage across all Hermes Agent sessions at openrouter.ai/activity, with filters for model and time range.
Common errors and fixes
Most setup issues fall into 2 categories:
- If Hermes can’t find your API key at all, the problem is local. This usually means the key was never saved to
~/.hermes/.env. - If the key exists but authentication still fails, the issue is on the account side. The key may be invalid, expired, or your OpenRouter account may have no remaining credits.
| Problem | Fix |
|---|---|
| ”No API key” / provider not found | Verify ~/.hermes/.env has the key, or rerun the setup command |
| 401 / 403 errors | Check key validity at openrouter.ai/keys and confirm your credit balance |
| Model not responding | Verify the model ID in ~/.hermes/config.yaml matches a valid provider/model-name at openrouter.ai/models |
| Context errors at startup | Switch to an OpenRouter model with at least 64K context |
If a model works in other setups but refuses to start in Hermes Agent, it’s usually the 64K context requirement, rather than a misconfiguration. Switch to a different model instead of debugging the YAML.
If you’re exploring other terminal-native agents, OpenRouter also provides a cookbook integration for OpenClaw, a multi-platform chat agent that uses the same backend.
Frequently Asked Questions
Is Hermes Agent the same as the Hermes 3 / Hermes 4 model?
No. Hermes Agent is the open-source autonomous CLI application by Nous Research; Hermes 3 and Hermes 4 are separate model families by the same team. You can run Hermes Agent using a Hermes model as its backend, or any model, through OpenRouter.
Is Hermes Agent free?
The agent is open-source (MIT) and free to run. You pay only for the model tokens it uses through your provider. See openrouter.ai/pricing for current rates, including free-tier models.
What model should I use with Hermes Agent on OpenRouter?
Start with ~anthropic/claude-sonnet-latest: it’s the documented default for basic setup and clears the 64K context requirement. Once you’re running, openrouter/auto auto-routes to a strong model without you having to choose, and openrouter/pareto-code optimizes cost specifically for coding tasks.
Do I need separate provider accounts?
For most supported models, no. One OpenRouter key grants Hermes Agent access to 400+ models from 70+ providers, with automatic failover.
If you hit an access error on a specific model, check that model’s page at openrouter.ai/models; some models require provider-specific eligibility. In most cases, switching to a different model resolves the issue.
Why does Hermes Agent reject my model at startup?
Most configurations require at least 64K context tokens; smaller windows may not hold the system prompt plus tool schemas. Switch to a larger-context model. Filter by context length at openrouter.ai/models to find candidates.
Does OpenRouter charge extra to run Hermes Agent?
There’s no markup on provider pricing. See openrouter.ai/pricing for current platform fees and billing details, including how failed requests are handled.