gahorouter 文档

简体中文

English

简体中文

English

Appearance

Hermes 接入 gahorouter API 指南 ​

本教程假设你已经在 gahorouter 注册了账号并拿到了 API Key。 下面只讲 Hermes 这边怎么配置。

1. 前置条件 ​

  • 一台 Linux / macOS / WSL2 机器（Windows 需要先装 WSL2）
  • 你的 gahorouter API Key（长得像 sk-xxxx... 的一串字符）
  • 知道你想用的模型名称（比如 claude-sonnet-4-6）

2. 安装 Hermes Agent ​

打开终端，粘贴下面这一行命令，回车：

bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

等它跑完（大概 1-3 分钟），然后执行：

bash
source ~/.bashrc

验证安装成功：

bash
hermes --version

应该看到类似这样的输出：

Hermes Agent v0.9.0 (2026.6.1)

如果提示 command not found，关掉终端重新打开再试。

3. 了解需要改什么 ​

Hermes 的所有配置都在一个文件里：

~/.hermes/config.yaml  <-- 主配置文件
~/.hermes/.env         <-- 存放 API Key（密钥）

我们要做两件事：

  1. 把 API Key 写到 .env 文件里
  2. 把 config.yaml 里的模型设置指向 gahorouter

4. 配置 API Key ​

4.1 打开 .env 文件 ​

bash
nano ~/.hermes/.env

如果你不会用 nano，也可以用任何文本编辑器打开这个文件。

4.2 添加你的 gahorouter API Key ​

在文件里加一行（把 sk-xxx 换成你自己的真实 Key）：

ANTHROPIC_API_KEY=sk-xxx你的gahorouter密钥xxx

4.3 保存退出 ​

如果用的 nano：按 Ctrl+O 保存，Ctrl+X 退出。

5. 配置 config.yaml ​

5.1 打开配置文件 ​

bash
nano ~/.hermes/config.yaml

5.2 找到文件最顶部的 model: 部分 ​

如果你是第一次安装，默认可能长这样：

yaml
model:
  model: ''
  provider: ''

5.3 改成下面的内容 ​

yaml
model:
  base_url: https://console.gahorouter.com
  model: claude-sonnet-4-6
  provider: anthropic

逐行解释：

  • base_url —— gahorouter 的 API 地址，替代默认的 api.anthropic.com
  • model —— 你要用的模型名称
  • provider —— 固定写 anthropic，告诉 Hermes 用 Anthropic Messages API 协议

5.4 保存退出 ​

Ctrl+O 保存，Ctrl+X 退出。

6. 验证配置 ​

6.1 启动 Hermes ​

bash
hermes

6.2 发一条消息测试 ​

进入 Hermes 后，输入：你好

如果一切正常，你会看到 AI 的回复。恭喜，配置成功！

6.3 如果报错了怎么办？ ​

常见错误和解决方法：

  • 错误：authentication_error / invalid api key
    • 原因：API Key 不对，或者没有正确写入 .env 文件
    • 解决：检查 ~/.hermes/.env 里的 ANTHROPIC_API_KEY 是否正确，前后不要有空格
  • 错误：connection error / timeout
    • 原因：网络问题，连不上 gahorouter
    • 解决：检查你的网络，试试 curl https://console.gahorouter.com 能不能通
  • 错误：model not found
    • 原因：模型名写错了
    • 解决：检查 config.yaml 里的 model 字段，确认 gahorouter 支持这个模型名
  • 错误：Hermes 无反应 / 用了别的 Key
    • 原因：可能 .env 里同时设了多个冲突的变量
    • 解决：如果你只用 gahorouter，.env 里只保留 ANTHROPIC_API_KEY 就行，把 OPENAI_API_KEY、OPENROUTER_API_KEY 等其它的删掉或注释掉

7. 完整配置文件示例 ​

下面是一个最小可用的 config.yaml（只保留必要部分）：

yaml
model:
  base_url: https://console.gahorouter.com
  model: claude-sonnet-4-6
  provider: anthropic
providers: {}
fallback_providers: []
toolsets:
  - hermes-cli
agent:
  max_turns: 90

对应的 .env 文件：

ANTHROPIC_API_KEY=sk-你的gahorouter密钥

8. 进阶：同时配置多个 Provider ​

如果你还想用其它 API（比如 DeepSeek），可以在 config.yaml 底部加：

yaml
custom_providers:
  - name: deepseek
    base_url: https://api.deepseek.com
    key_env: DEEPSEEK_API_KEY

然后在 .env 里加：

DEEPSEEK_API_KEY=你的DeepSeek密钥

9. Fallback 自动切换备用 API ​

当主 API 出现故障时（限流、过载、连接失败），Hermes 可以自动切换到备用 API，整个过程无需人工干预，用户几乎无感知。

9.1 触发条件 ​

以下情况会自动激活 fallback：

  • 429 限流 / 配额耗尽（主 API 会冷却约 1 小时）
  • 503 / 529 服务过载
  • 连接失败 / DNS 解析失败
  • 超时
  • 模型不存在

触发逻辑：主 API 连续重试 3 次失败后，自动切换到 fallback。

注意：fallback 在一次会话中只激活一次，激活后当前 session 全程使用备用 API。

9.2 配置单个 Fallback ​

在 config.yaml 顶层（不是 model 里面，不是 custom_providers 里面）添加：

yaml
fallback_model:
  provider: custom
  model: deepseek-chat
  base_url: https://api.deepseek.com
  api_key_env: DEEPSEEK_API_KEY

同时在 ~/.hermes/.env 里添加备用 API 的密钥：

DEEPSEEK_API_KEY=sk-你的DeepSeek密钥

这样配置后，gahorouter 主 API 挂掉时，会自动切换到 DeepSeek（也可以是其余模型或者供应商）。

9.3 配置多级 Fallback 链 ​

如果想配置多个备用 API 按顺序依次尝试，使用 fallback_providers（列表格式）：

yaml
fallback_providers:
  - provider: custom
    model: deepseek-chat
    base_url: https://api.deepseek.com
    api_key_env: DEEPSEEK_API_KEY
  - provider: openrouter
    model: anthropic/claude-sonnet-4-6
    # 需要 OPENROUTER_API_KEY 写入 .env

9.4 验证 Fallback 是否生效 ​

Fallback 激活时，Hermes 会在界面底部显示提示：

🔄 Fallback model: deepseek-chat (custom)

日志里也会出现：

Fallback activated: claude-sonnet-4-6 → deepseek-chat (custom)

9.5 支持作为 Fallback 的 Provider ​

内置 provider（直接写 provider 名称即可，无需 base_url）：

openrouter   -- 需要 OPENROUTER_API_KEY
zai          -- 需要 ZAI_API_KEY
kimi-coding  -- 需要 KIMI_API_KEY
minimax      -- 需要 MINIMAX_API_KEY
deepseek     -- 需要 DEEPSEEK_API_KEY（内置支持）

自定义 OpenAI 兼容端点（需要指定 base_url 和 api_key_env）：

yaml
fallback_model:
  provider: custom
  model: 模型名称
  base_url: https://你的API地址
  api_key_env: 存放密钥的环境变量名

9.6 完整配置示例（gahorouter 主 + DeepSeek 备） ​

config.yaml：

yaml
model:
  base_url: https://console.gahorouter.com
  model: claude-sonnet-4-6
  provider: anthropic

fallback_model:
  provider: custom
  model: deepseek-chat
  base_url: https://api.deepseek.com
  api_key_env: DEEPSEEK_API_KEY

custom_providers:
  - name: deepseek
    base_url: https://api.deepseek.com
    key_env: DEEPSEEK_API_KEY

.env：

ANTHROPIC_API_KEY=sk-你的gahorouter密钥
DEEPSEEK_API_KEY=sk-你的DeepSeek密钥