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

> https://router.one/zh/integrations/hermes-agent 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-29

Hermes Agent 是 Nous Research 开源（MIT）的 agent：既有带工具的终端交互会话，也有能在 Telegram、Discord、Slack 等应用里应答的消息网关。它支持任意 OpenAI 兼容端点，所以一把 Router One Key 就能用上目录中的 Claude、GPT、Gemini、Grok 和 DeepSeek 对话模型；它发出的每个模型请求（包括辅助任务）都会出现在控制台 → 日志里，附带 Token 与费用。可以用 hermes model 向导中的 Custom endpoint 添加 Router One，也可以在 config.yaml 里写成命名 provider，后者还能让某个模型走 Anthropic Messages 或 Responses transport。按 Hermes Agent v0.21.5（v2026.9.24，2026-09-24 发布）的文档与源码核对（2026-09-29）。

## 安装 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 的请求。

`terminal`

```text
# 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：

`config.yaml`

```yaml
# ~/.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。

`config.yaml`

```yaml
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
```

| transport | api | 适用的 Router One 模型 ID |
| --- | --- | --- |
| chat_completions（默认） | https://api.router.one/v1 | 目录中的全部对话模型：Claude、GPT、Gemini、Grok 与 DeepSeek 的 ID |
| anthropic_messages | https://api.router.one | Claude 系列 ID（含 aws/claude-… 与 vertex/claude-… 渠道 ID），以及 deepseek-v4.1-flash、deepseek-v4-flash |
| codex_responses | https://api.router.one/v1 | GPT 系列 ID（含 azure/gpt-… 渠道 ID），以及 deepseek-v4.1-flash、deepseek-v4-flash 与 Grok 对话模型 ID |

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

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。

`config.yaml`

```yaml
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；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### Hermes 把 Router One 的配置存在哪里？

存在 Hermes 主目录下的 config.yaml 中：macOS、Linux 与 WSL2 上是 ~/.hermes，原生 Windows 上是 %LOCALAPPDATA%\hermes（除非 HERMES_HOME 指向别处）。Key 存在同一目录的 .env 文件里。hermes config path 和 hermes config env-path 会输出这两个文件的位置，hermes config edit 会用编辑器打开配置。Custom endpoint 向导把 Key 存为 HERMES_CUSTOM_API_ROUTER_ONE_API_KEY，config.yaml 里只引用它；用命名 provider 时，由 key_env 指定变量名。不要把这两个文件放进 dotfile 仓库或共享备份。

### 设置了 OPENAI_BASE_URL，Hermes 仍然没有调用 Router One，为什么？

按 Hermes 的 provider 文档，OPENAI_BASE_URL 只对它的 openai-api provider 生效；自定义端点和命名 provider 从 config.yaml 读取地址。请运行 hermes model 选择 Custom endpoint，或像上面的示例那样把 model.provider 设为 custom:router-one，然后开启新会话。对话中的 /model 命令只能在已配置的 provider 之间切换，不能新增 provider。

### 能在同一个 Hermes 会话里切换 Claude 和 GPT 吗？

可以，前提是 provider 已经配置好。/model custom:router-one:openai/gpt-5.6-sol 会切换到 router-one 条目上的 GPT ID；如果你定义了 anthropic_messages 条目，/model custom:router-one-claude:anthropic/claude-sonnet-5 会切换到该条目上的 Claude ID。写在 model 一节的 context_length 会在切换时失效，所以请在 providers.<名称>.models 下为用到的每个模型分别设置 context_length。

### 模型列表里有图像模型，还有没有能力标签的 ID，该选哪个？

GET /v1/models 会返回整个目录，其中包括图像生成模型，以及模型页没有列出任何能力的 ID。Hermes 依靠工具调用工作，请选择 /models 详情页标明支持工具调用的对话模型；其他 ID 先试一次工具调用。图像生成 ID 无法处理 Hermes 的对话轮次。

### 可以用 pip install hermes-agent 安装吗？

那样装到的是旧版本。截至 2026-09-29，PyPI 上的 hermes-agent 包是 0.19.0（2026-07-20 发布），而 GitHub 发布版和官方安装脚本已是 v0.21.5（v2026.9.24）。安装脚本还会为 Hermes 准备独立的 Python 环境与依赖，之后用 hermes update 保持更新即可。

### Hermes Agent 能通过网关用哪些模型？

选用当前目录中同时支持 Hermes Agent 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只说明它从自身配置或 GET /v1/models 读到了这个 ID，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。Hermes 发往 Router One 的模型请求在中国大陆无需 VPN，配置与其他地区相同。安装和更新 Hermes 是另一回事：安装脚本会从 GitHub 克隆 Hermes 仓库并下载 Python 工具链，能否顺利完成取决于你的网络能否访问这些站点。

### 报 401/402/403/429 怎么排查？

先到控制台 → 日志核对这条请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- Hermes Agent 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- GitHub Copilot CLI 接入：https://router.one/zh/integrations/copilot-cli
- Cherry Studio 接入：https://router.one/zh/integrations/cherry-studio
- CLI 配置指南：Hermes Agent 标签页：https://router.one/zh/docs/guides/cli-setup
- OpenClaw：同一把 Key 的自托管助手：https://router.one/zh/integrations/openclaw
- 通过网关使用工具调用：https://router.one/zh/llm-tool-calling
- Hermes Agent 官方文档：AI providers：https://hermes-agent.nousresearch.com/docs/integrations/providers
- Hermes Agent 中文 README：https://github.com/NousResearch/hermes-agent/blob/main/README.zh-CN.md
- Hermes Agent 发布记录：https://github.com/NousResearch/hermes-agent/releases
- 统一 LLM API 网关概览：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/hermes-agent
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md