Hermes Agent 接入

Hermes Agent 是 Nous Research 提供的 Agent 客户端。本页使用它的 Custom endpoint 自定义端点，将主对话模型接入 RouteFast/sub2api 的 GPT 路由。

配置项	本页填写值
RouteFast 密钥分组	OpenAI-ChatGPT
API base URL	https://api.routefast.ai/v1
API 模式	chat_completions（OpenAI Chat Completions）
实际聊天端点	POST https://api.routefast.ai/v1/chat/completions
模型 ID	从这把 Key 的模型列表选择；本文以 gpt-5.6-terra 为例

1. 安装 Hermes

在准备使用 Hermes 的电脑上，按 Hermes 官方安装文档 选择对应系统的安装方式。本教程使用命令行客户端；macOS、Linux 或 WSL2 的官方命令为：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安装器会下载程序及依赖，并可能进入初始配置。确认信任官方安装脚本后再执行；原生 Windows 请使用官方安装页的 PowerShell 路径。

安装后，在新终端检查：

hermes --version
hermes chat --help

记录版本号，方便排障。安装过程中如果需要选择模型提供商，按下文选择自定义端点；已有安装可直接运行 hermes model。

2. 准备分组密钥与模型 ID

1. 登录 RouteFast 控制台，在 API 密钥 创建一把 OpenAI-ChatGPT 分组密钥，建议命名为 hermes-local。
2. 按 快速开始：检查模型列表，使用这把密钥查询 GET /v1/models。
3. 复制返回结果中的完整模型 ID。只有当列表包含 gpt-5.6-terra 时，才使用本页示例值。

不要自行加上 openai/、openrouter/ 或 routefast/ 前缀，也不要把控制台的模型显示名称当成模型 ID。模型列表成功仅证明查询接口的网络与鉴权可用，仍需完成一次生成请求。

3. 备份已有配置

Hermes 默认在用户目录的 ~/.hermes/ 保存配置：config.yaml 存设置，.env 存密钥，auth.json 存 OAuth 凭证。使用过 HERMES_HOME 或命名 profile 时，应备份该实例实际使用的目录。可运行 hermes config edit 确认打开的是哪一个 config.yaml。配置位置与命令见 Hermes 配置文档。

退出当前 Hermes 会话，然后复制已有的 config.yaml 与 .env，分别保存为 config.yaml.before-routefast-20260911 和 .env.before-routefast-20260911；若同名备份已存在，换一个名称。新安装没有这些文件时无需复制。备份也包含敏感信息，应和原文件一样限制访问，不要放进项目仓库或公开分享。

4. 通过向导保存 RouteFast

在终端运行，注意此时不在 Hermes 聊天会话内：

hermes model

按提示完成以下步骤。不同版本的菜单文案或顺序可能略有变化，应核对每项的实际值。

1. 选择 Custom endpoint，官方文档也将它写作 Custom endpoint (self-hosted / VLLM / etc.)。
2. 在 API base URL 中明确输入 https://api.routefast.ai/v1。不要填控制台地址 https://routefast.ai，也不要附加 /chat/completions。
3. 在 API key 中粘贴完整的 OpenAI-ChatGPT 分组 Key。即使向导显示旧值，也应重新填写，避免留空后沿用其他提供商的密钥。
4. 在 API mode 选择 OpenAI Chat Completions / chat_completions。这是本页对接的协议；不要因模型名称含 GPT 就选择 ChatGPT/Codex 订阅登录。
5. 从探测到的列表选择已确认的模型 ID，或手动输入，例如 gpt-5.6-terra。如果探测失败，先对照上一步的模型查询结果排障，不要将“仍然保存配置”视为连通成功。
6. Context length 可先留空让客户端探测。若识别错误，只填写已确认的实际上下文窗口；这个值不是单次输出 Token 上限，不能靠填大数值扩大模型能力。
7. Display name 可填写 RouteFast GPT。保存后检查向导显示的模型与地址。

更多自定义端点与 API 模式说明见 Hermes 提供商文档。

这里使用 RouteFast API Key

ChatGPT or Codex Subscription、Nous Portal 和 OpenRouter 是其他提供商入口，不是本页的 RouteFast 接入方式。不要把 RouteFast Key 填入它们的登录流程或官方账户页面。会话内的 /model 主要用于切换已经配置好的提供商；初次添加端点请使用终端里的 hermes model。

配置与密钥如何持久保存

向导保存后的模型、提供商、地址和协议位于 config.yaml。自定义端点 Key 保存到同一 Hermes 数据目录的 .env，YAML 中保存环境变量引用或 key_env 引用；终端会显示所用变量名。保留向导生成的实际变量名，不要只修改引用的一端。 旧版配置中可能直接包含 api_key，因此 YAML 本身也应按敏感文件处理。

新格式的命名端点位于 providers:，其中地址字段通常为 api，协议字段为 transport；主模型段的对应字段为 base_url 和 api_mode。旧版还可能使用 custom_providers:。已存在的配置应修改原条目，避免再追加第二个同名 YAML 段。字段格式与迁移说明见 官方命名提供商说明。

保存到该实例的 .env 后，后续启动可以继续读取；如果改为由当前 shell 或密码管理器注入密钥，则必须在每次启动时提供相同的变量。OPENAI_BASE_URL 不是自定义端点的通用持久配置方式，模型与地址以向导写入的 YAML 为准。不要把密钥写进启动命令参数、项目文件或对话消息。

5. 检查配置并发起一次简短请求

先检查不含密钥的字段：

hermes config get model.provider
hermes config get model.default
hermes config get model.base_url
hermes config get model.api_mode

初次向导配置通常显示 custom、所选模型、https://api.routefast.ai/v1 与 chat_completions。重新选择已保存的命名端点后，提供商可能显示为对应命名 ID，地址则来自 providers: 条目；此时用 hermes config edit 在本地核对对应条目即可。不要为了排障打印、截图或发送 model.api_key、完整 .env 或凭证文件。

先运行 hermes tools，检查并关闭此次连接测试不需要的工具。然后在一个不含敏感业务文件的目录运行：

hermes chat --oneshot -q "不要调用工具，只回复 OK"

--oneshot 表示回答后退出；当前官方版本单用 -q 在交互终端中可能继续保留会话。如果已安装版本没有此选项，可启动 hermes，手动输入同一句提示，收到回复后退出。命令语义见 Hermes CLI 参考。

这一步会产生实际模型用量。收到正常回复后，打开 RouteFast 使用记录，按时间、密钥和模型核对 Token 与费用。Hermes 的系统提示、历史、工具定义及辅助请求也可能产生用量，因此“只回复 OK”不等于只计两个字符，也不保证只有一条记录。费用口径见 计费与用量。

完成标准是“客户端收到正常生成结果，并能核对对应使用记录”。一条文本请求成功后，再按需逐项验证流式、工具调用或图片；不要一开始就运行长任务。

辅助模型与外部工具

Hermes 除主对话外，还可能调用标题生成、上下文压缩、视觉分析等辅助模型。当前官方配置文档说明 auxiliary.*.provider: auto 默认使用主模型，但已有配置中的显式覆盖、子 Agent 设置或备用提供商会改变路由。可通过 hermes model 中的 Configure auxiliary models 检查，并查看 auxiliary、delegation 与 fallback_providers 等已有配置。依据见 Hermes 辅助模型配置。

搜索、浏览器、语音、图像生成、MCP 等工具还可能使用独立服务和凭证。主模型接入 RouteFast 不代表所有工具流量、模型请求或费用都经过 RouteFast，也不会自动获得这些服务的 API Key。先在 hermes tools 查看具体工具要求，再按对应服务配置；本站文档覆盖范围见 接口与兼容性。

恢复原配置

停止使用该配置的 Hermes 会话；若另有常驻 gateway，也先停止相应进程。先另存当前 config.yaml 与 .env，再把第 3 步的备份分别复制回原文件名，最后重新启动 Hermes 并检查模型、地址与协议。仅想切换模型时，也可重新运行 hermes model 选择原提供商。

恢复配置不会撤销已经发生的用量，也不会禁用 RouteFast Key。若不再使用该密钥，在 API 密钥 中禁用；密钥泄露时应轮换，不要仅恢复本地备份。

常见问题

现象	优先检查
hermes: command not found	安装是否完成；重开终端，并按官方安装页检查 PATH
401 或密钥无效	是否填写完整 RouteFast Key；是否沿用旧密钥；是否启动了另一个 profile；Key 是否被禁用
403	根据错误体检查余额、有效期、IP 限制及分组权限，不要只重填 Key
model_not_found	Key 是否属于 OpenAI-ChatGPT，模型 ID 是否与这把 Key 的列表完全一致
404、路径错误或返回 HTML	Base URL 是否是 https://api.routefast.ai/v1；是否重复附加 /v1 或 /chat/completions；API mode 是否正确
保存成功，但启动仍连接旧提供商	是否使用同一数据目录/profile；是否有命令行覆盖；新开会话并核对 model 与 providers
主对话正常，标题、压缩或工具失败	辅助模型覆盖、备用路由、工具独立凭证或对应能力；按出错组件检查，不要直接更换所有 Key
429	区分 Key 总金额额度、费用窗口、并发和请求速率，按恢复条件处理；不要持续自动重试
上下文或工具参数错误	模型上下文识别是否正确、当前协议是否支持该字段；先复现最小文本请求，再逐项增加能力

Claude 密钥属于 Anthropic-Claude 分组，使用 Anthropic Messages 协议与根地址 https://api.routefast.ai。不要只把本页 GPT 示例里的模型名换成 Claude 名称；Claude 接入可参考 Claude API 快速开始 与 Claude Code。

仍有问题时，保留 Hermes 版本、发生时间、脱敏后的提供商/地址/模型/协议、HTTP 状态码及请求 ID（如有），按 故障排查 联系支持。不要发送完整 API Key、凭证文件或业务对话。

官方文档

• Hermes：安装
• Hermes：LLM and Model Providers
• Hermes：配置与辅助模型
• Hermes：CLI 命令参考