Hermes Agent 在 OpenRouter 上的使用指南：设置、模型与路由

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 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.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 自动解析到某个模型系列的最新可用版本，而不是将你锁定在某个特定发布版本上。

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

当你不想做选择时，使用自动路由

openrouter/auto 是一种可选的路由模式。它会根据 NotDiamond 的路由决策，为每个请求自动挑选一个强大的模型。如果你没有偏好的模型，只想获得可靠的结果而不做任何基准测试，这是一个很好的起点。

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

提供商路由、回退与辅助模型

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

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

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

提供商路由控制

provider_routing 部分控制由哪个提供商处理每个请求：

设置 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 类：

1. 如果 Hermes 完全找不到你的 API key，问题出在本地。这通常意味着该 key 从未保存到 ~/.hermes/.env。
2. 如果 key 存在但认证仍然失败，问题出在账户侧。该 key 可能无效、已过期，或者你的 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 了解当前的平台费用和计费详情，包括失败请求的处理方式。