把 Router One 配置为 Hermes Agent 的自定义端点

安装 Hermes Agent 0.21.5，并创建专用 Key

请用官方一行安装脚本安装，不要用 pip：截至 2026-09-29，PyPI 上的 hermes-agent 包仍停在 0.19.0（2026-07-20），而 GitHub 发布版与安装脚本已是 v0.21.5。在 macOS、Linux 与 WSL2 上，安装脚本只需要 git 和 curl，Python、Node.js 等依赖由它自行安装。Windows 支持原生安装：在 PowerShell 中运行下面的 PowerShell 命令，Hermes 会装在 %LOCALAPPDATA%\hermes（在 WSL2 里则与 Linux 相同，装在 ~/.hermes）。在终端中运行时，安装脚本最后会启动 hermes setup，其中的 Model & Provider 一节与 hermes model 是同一流程，可以当场填入下一节的 Router One 配置，也可以稍后再配。然后在控制台 → API 密钥点「创建密钥」，为 Hermes 单独建一把 Key 并设置 maxSpend 上限：Agent 任务的每一轮模型调用都是一次计费请求，Hermes 的辅助任务还会另外产生请求，这个上限就是硬性止损，专用 Key 也便于在日志里集中查看 Hermes 的请求。

# macOS、Linux、WSL2（需要 git 和 curl）
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc     # 或 source ~/.zshrc，也可以直接新开一个终端

# Windows（原生 PowerShell）
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

hermes --version

把 Hermes Agent 配置到 Router One base URL

在终端里（不要在对话会话中）运行 hermes model，选择 Custom endpoint。在 API base URL 一步填 https://api.router.one/v1，在 API key 一步粘贴专用 Key。随后 Hermes 会用 GET /v1/models 检查端点：Router One 只在带 Key 时响应这个请求，返回的列表包含目录中的全部 ID（也包括图像生成模型），所以请直接输入精确的对话模型 ID，不要按序号挑选。在 Select API compatibility mode 一步选 2（Chat Completions）：api.router.one 不在 Hermes 的自动识别名单里，而 Chat Completions 覆盖全部对话模型。模型名填 /models 上的 ID，例如 anthropic/claude-sonnet-5；Context length in tokens 先留空（见下方上下文一节），Display name 填 Router One。Hermes 会把 Key 以 HERMES_CUSTOM_API_ROUTER_ONE_API_KEY 的名字存进它的 .env 文件，并把 provider: custom、Base URL、API 模式和模型写入 config.yaml，配置文件里只引用这个变量。如果要让 Router One 与其他 provider 并列，或以后再加一种 transport，可以改为在 config.yaml 中定义命名 provider：

API base URL (hermes model → Custom endpoint)

https://api.router.one/v1

# ~/.hermes/config.yaml — native Windows / 原生 Windows: %LOCALAPPDATA%\hermes\config.yaml
providers:
  router-one:
    api: https://api.router.one/v1
    key_env: ROUTER_ONE_API_KEY      # set in Hermes' .env / 写在 Hermes 的 .env 中
    transport: chat_completions

model:
  provider: custom:router-one
  default: anthropic/claude-sonnet-5

compression:
  threshold_tokens: 256000         # v0.21.5 default; below 200000 for Grok IDs / v0.21.5 默认值；用 Grok ID 时设到 200000 以下

# ~/.hermes/.env
# ROUTER_ONE_API_KEY=sk-your-router-one-key

为每个 Router One 模型 ID 选择 transport

每个命名 provider 只使用一种 transport：chat_completions（字段留空时 Hermes 也用它）、anthropic_messages 或 codex_responses。Router One 在 Chat Completions 上提供全部对话模型，在 Anthropic Messages 上提供 Claude 系列与 DeepSeek V4 的 ID，在 Responses 上原生提供 GPT 系列、DeepSeek V4 与 Grok 对话模型，所以一个 chat_completions 条目就能覆盖全部模型，再加一个条目只是让某个系列换用另一种接口格式。api 的写法随 transport 而定：Hermes 的 Anthropic 客户端会去掉末尾的 /v1（其 SDK 会自行拼接 /v1/messages），所以两种写法都可以；两种 OpenAI transport 则在 /v1 后面拼接 /chat/completions 或 /responses。通过 codex_responses 发送 Claude ID，会在调用任何模型之前被 HTTP 400 拒绝（model '<id>' must be called via /v1/messages or /v1/chat/completions）；通过 anthropic_messages 发送 Claude 与 DeepSeek 系列以外的对话模型，会收到提示 must be called via /v1/chat/completions 的 400。Hermes 在 OpenAI transport 上用 Authorization: Bearer 传 Key，对第三方 Anthropic 主机用 x-api-key；Router One 两种都接受，所以各条目可以共用同一把 Key。

providers:
  router-one:
    api: https://api.router.one/v1
    key_env: ROUTER_ONE_API_KEY
  router-one-claude:
    api: https://api.router.one
    key_env: ROUTER_ONE_API_KEY
    transport: anthropic_messages

# 在 Hermes 会话中切换：
#   /model custom:router-one:openai/gpt-5.6-sol
#   /model custom:router-one-claude:anthropic/claude-sonnet-5

自己设定上下文长度与压缩时机

Hermes 按模型的上下文窗口安排对话压缩。你设置的 context_length（写在 model 一节，或写在 providers.<名称>.models 下的单个模型里）始终优先；留空时，Hermes 会依次尝试缓存、端点 /models 的返回和公开的模型登记数据，最后退回内置默认值。Router One 的 GET /v1/models 返回中没有 Hermes 会当作窗口读取的字段，所以自动识别出的值可能与 Router One 模型页不一致。Hermes 启动时会以 Context limit 显示正在使用的窗口，并把手动设置的值标为 pinned。/models 的模型页列出每个模型的完整窗口，要设置 context_length 时就填这个值。按 Hermes v0.21.5 的配置文档与源码，压缩在两个触发值中较低的一个处发生：compression.threshold（窗口的 0.50，窗口小于 512K 时提高到 0.75）和 compression.threshold_tokens（默认 256000）。所以 1M 窗口的会话大约在输入达到 256,000 Token 时压缩，在此之前每个输入 Token 都计费。部分模型页还列出长上下文价格：单次请求的输入超过门槛后，整次请求都按这一价格计费，openai/gpt-5.6-sol 的门槛是 272,000 Token，grok-4.7 是 200,000。默认的 256000 低于 openai/gpt-5.6-sol 的 272,000 门槛，但高于 grok-4.7 的 200,000 门槛；使用 Grok ID 时，如果想让长会话在到达门槛之前压缩，请把 compression.threshold_tokens 设在 200000 以下（例如 190000）。按 Hermes 文档，切换模型后这个值仍然生效。另外，按 Hermes 文档，在 codex_responses transport 上，gpt-5.6-sol 这类 GPT 模型名会从 Hermes 的 Codex 表中取窗口（多数为 272K），除非你设置了 context_length；按其源码，Router One ID 中的 openai/ 前缀不影响这一点。

推理强度、辅助任务与 embeddings

按 Hermes 文档，未设置推理强度时，chat_completions 请求会带上 reasoning_effort: medium；用 /reasoning 或 agent.reasoning_effort 设置的级别会原样发到端点，最高到 max。对 Claude 系列 ID，Router One 不会把 reasoning_effort 转换为 thinking 设置；Claude Opus 5.5 例外，会映射到 output_config.effort。其他模型可能忽略它，也可能以 400 拒绝请求，所以请先在控制台 → 日志里查看最初几次请求的状态，修改级别后再看一次。Hermes 还会用主模型运行辅助任务，包括会话标题、上下文压缩和图片描述，除非你把它们指到别处；每项辅助任务都是同一把 Key 上的又一次请求。要把某项任务交给更便宜的 Router One 模型，把 auxiliary.<任务>.provider 设为你的命名 provider、auxiliary.<任务>.model 设为精确 ID（见下例），也可以在 hermes model 中选择 Configure auxiliary models。Router One 不提供 embeddings 端点；如果你启用了需要嵌入模型的 Hermes 功能，请为它另配 provider。

auxiliary:
  compression:
    provider: router-one
    model: google/gemini-3.8-flash
  vision:
    provider: router-one
    model: google/gemini-3.8-flash

Hermes 发出哪些请求，4xx 报错怎么看

每一轮模型调用都是一次请求：读文件、执行命令、改代码的任务每一轮工具调用都会发一次，上面的辅助任务还会另外产生请求，所以请在控制台 → 日志中按 Hermes 专用的 Key 筛选。每条记录显示模型、Token、费用、状态、总耗时，以及产生过输出的流式请求的首字延迟（TTFT）。按状态码判断错误：401 表示 Key 缺失或错误（用 key_env 时，确认该变量确实写在 Hermes 的 .env 里）；402 表示钱包余额或该 Key 的 maxSpend 已用完，触顶后这把 Key 的请求返回 402，其他 Key 不受影响；404 通常是路径错误或 ID 不在目录中，请从 /models 重新复制 ID；400 且提示 must be called via，说明当前 transport 不服务这个 ID。没有到达 Router One 的调用不会留下记录，这时应回头检查本地配置。

Hermes Agent 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Hermes Agent 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个客户端或应用单独建 API Key，并设置 maxSpend 消费上限。

Hermes Agent 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在请求日志里核对 Hermes Agent 的调用

先在 Hermes Agent 发出一次简单文本请求，再到控制台 → 日志按时间、模型和 request_id 找到这条记录，核对 Token、花费、总耗时和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题