通过 Telegram 配置 Hermes Agent 主模型与回退模型教程

Hermes Agent 的主模型和回退模型都在 ~/.hermes/config.yaml 里配置。如果你是通过 Telegram 远程使用 Hermes，可以直接让它帮你改配置文件，不需要 SSH 登服务器。

这篇记录完整的配置流程，包括踩坑和源码修复。

配置文件位置

所有模型配置都在 ~/.hermes/config.yaml，核心字段：

1
2
3
4
5
6
7
8
9
model:
  default: zai-org/GLM-5.1-FP8    # 主模型名称
  provider: custom                  # 供应商类型
  base_url: https://api.xxx/v1     # API 地址（custom 供应商需要）
  api_key: your-api-key             # API 密钥（custom 供应商需要）

fallback_model:                     # 回退模型
  provider: openrouter
  model: anthropic/claude-sonnet-4

主模型配置

使用内置供应商

OpenRouter、Anthropic 等内置供应商只需要 provider 和 model 两个字段：

1
2
3
model:
  provider: openrouter
  default: anthropic/claude-sonnet-4

API 密钥通过环境变量设置，在 ~/.hermes/.env 里加：

1
OPENROUTER_API_KEY=sk-or-xxxxx

使用自定义供应商（Custom Endpoint）

自建 API 代理、第三方中转站或者自己的模型服务，需要配全 base_url 和 api_key：

1
2
3
4
5
model:
  default: zai-org/GLM-5.1-FP8
  provider: custom
  base_url: https://api.us-west-2.modal.direct/v1
  api_key: modalresearch_xxxxx

custom 供应商走 OpenAI 兼容协议，Hermes 会把请求发到 base_url/chat/completions。

在 Telegram 里让 Agent 改配置

直接跟 Hermes 说：

把主模型改成 zai-org/GLM-5.1-FP8，供应商 custom，API 地址 https://api.us-west-2.modal.direct/v1，API 密钥是 xxxxx

Agent 会自动编辑 config.yaml，改完重启 Gateway 生效。

回退模型配置

回退模型的作用：主模型遇到限流（429）、服务错误（503）或连接失败时，Hermes 自动切换到回退模型继续对话，聊天记录和上下文不会丢。

单个回退模型

最简单的配置，只配一个备选：

1
2
3
4
5
fallback_model:
  provider: custom
  model: gemini-3.1-pro-high
  base_url: https://api.886423.xyz/v1
  api_key: TAOzi#1024

多个回退模型（链式切换）

这是这次的新发现：Hermes 的运行时代码支持把 fallback_model 配成数组，按顺序依次尝试：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
fallback_model:
  - provider: custom
    model: gemini-3.1-pro-high
    base_url: https://api.886423.xyz/v1
    api_key: secret-1
  - provider: custom
    model: z-ai/glm4.7
    base_url: https://api.us-west-2.modal.direct/v1
    api_key: secret-2
  - provider: custom
    model: claude-sonnet-4-6
    base_url: https://api.886423.xyz/v1
    api_key: secret-1

切换逻辑：主模型挂了，尝试第 1 个回退；也挂了，尝试第 2 个；以此类推，全部失败才报错。

配置校验不认 list 的坑

这是最坑的地方。Hermes 的运行时（run_agent.py）支持 fallback_model 为列表，但配置校验层（hermes_cli/config.py 第 1485 行）只认 dict：

1
2
Config issues detected in config.yaml:
  fallback_model should be a dict with 'provider' and 'model', got list

Gateway 启动时会报这个错。

修复方法

编辑 ~/.hermes/hermes-agent/hermes_cli/config.py，找到校验 fallback_model 的代码块（搜索 fallback_model should be a dict），把校验逻辑改为同时支持 dict 和 list：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 修改前：只认 dict
if not isinstance(fb, dict):
    issues.append(ConfigIssue("error", ...))

# 修改后：同时认 dict 和 list
fb_list = fb if isinstance(fb, list) else [fb]
if not isinstance(fb, (dict, list)):
    issues.append(ConfigIssue("error", ...))
else:
    for i, entry in enumerate(fb_list):
        # 逐个校验每个 entry 的 provider 和 model 字段
        ...

改完重启 Gateway，报错消失。

凭据池：同一供应商多密钥轮换

同一个供应商有多个 API 密钥（比如两个 OpenRouter 账号），可以用凭据池做轮换，避免单个密钥被限流：

1
2
3
4
5
6
7
8
9
# 添加第二个密钥
hermes auth add openrouter --api-key sk-or-xxxxx

# 查看当前凭据池
hermes auth list

# 设置轮换策略，在 config.yaml 里：
credential_pool_strategies:
  openrouter: round_robin    # fill_first | round_robin | least_used | random

凭据池和回退模型是两套独立机制：池子是同一个供应商内轮换密钥，回退是跨供应商切换模型。优先级是先轮换密钥，全部密钥用完再切回退模型。

重启 Gateway 使配置生效

改完 config.yaml 之后需要重启：

1
systemctl restart hermes-gateway

检查状态：

1
2
systemctl status hermes-gateway
journalctl -u hermes-gateway -n 20

启动日志里应该能看到回退模型的加载信息。配了多个回退的话，会显示：

1
Fallback chain (6 providers): gemini-3.1-pro-high (custom) -> z-ai/glm4.7 (custom) -> ...

完整容灾架构

配置完毕后，Hermes 有了多层保险：

1
2
3
4
5
6
7
用户消息
  -> 主模型 (GLM-5.1)
  -> 429/503? -> 凭据池轮换密钥 (如果配了)
  -> 所有密钥耗尽? -> 回退模型 1 (Gemini)
  -> 也挂了? -> 回退模型 2 (GLM-4.7)
  -> ...
  -> 全部失败 -> 报错

小结

主模型和回退模型都在 config.yaml 里配，custom 供应商要加 base_url 和 api_key
回退模型支持数组格式，按顺序链式切换，但配置校验代码需要小改才能识别 list 格式
凭据池和回退模型是两套独立机制，可以同时使用
改完配置记得重启 Gateway

有问题欢迎交流。