Hermes Agent config.yaml 完全指南：模型、路由、故障转移

Hermes Agent 的全部行为由一个 YAML 配置文件控制——config.yaml。这篇文章用官方文档 + 真实配置，把模型配置、自定义提供商、故障转移、辅助模型等核心机制讲清楚，附带常见错误和标准写法。

一、配置文件位置

配置文件由 hermes model 交互式向导生成，也可以直接编辑。每次修改后无需重启 Hermes，模型切换类配置立即生效。

二、模型配置（model 节）

model: 是配置文件的入口，决定默认使用哪个提供商和模型。

标准写法

model:
  default: sensenova-6.7-flash-lite   # 模型名称
  provider: custom:sensenova          # 提供商
  base_url: https://token.sensenova.cn/v1   # API 地址

关键字段说明

两个容易混淆的设置

• context_length = 总上下文窗口，输入 + 输出的合计预算。Hermes 用它决定何时压缩历史。
• max_tokens = 单次响应的输出上限。与对话历史长度无关。

文档原文：context_length 是总上下文窗口——输入和输出 token 的合计预算。model.max_tokens 是输出上限——模型在单次响应中最多可生成的 token 数。

模型 ID 别名

default: 和 model: 作为键名效果完全相同：

model:
  model: sensenova-6.7-flash-lite   # 与 default 等价

三、自定义提供商（custom_providers）

当提供商不在 Hermes 一等支持列表中（如 SenseNova、LongCat、Together AI），使用 custom_providers: 定义。

标准写法

custom_providers:
  - name: SENSENOVA
    base_url: https://token.sensenova.cn/v1
    key_env: SENSENOVA_API_KEY
    models:
      sensenova-6.7-flash-lite:
        context_length: 128000
      deepseek-v4-flash:
        context_length: 1000000

字段说明

api_mode 可选值

命名自定义提供商的切换语法

配置多个自定义端点后，用三段式语法在会话中切换：

/model custom:local:qwen-2.5       # 使用 "local" 端点 + qwen-2.5 模型
/model custom:work:llama3-70b      # 使用 "work" 端点 + llama3-70b 模型

实战：Together AI 配置

custom_providers:
  - name: together
    base_url: https://api.together.xyz/v1
    key_env: TOGETHER_API_KEY

model:
  default: MiniMaxAI/MiniMax-M2.7
  provider: custom:together

对应 .env 文件：

TOGETHER_API_KEY=your-together-key

实战：多个提供商组合

custom_providers:
  - name: together
    base_url: https://api.together.xyz/v1
    key_env: TOGETHER_API_KEY
  - name: groq
    base_url: https://api.groq.com/openai/v1
    key_env: GROQ_API_KEY
  - name: perplexity
    base_url: https://api.perplexity.ai
    key_env: PERPLEXITY_API_KEY

model:
  default: MiniMaxAI/MiniMax-M2.7
  provider: custom:together

四、一等提供商（无需 custom_providers）

一等提供商（First-class providers） 是 Hermes 内置原生支持的提供商，有专属的 provider ID。

核心特点：

1. 不需要 custom_providers: — 直接写 provider: deepseek 即可
2. Hermes 自动处理特殊行为 — 如 Anthropic 的 token 自动刷新、xAI 的 prompt 缓存、Z.AI 的端点自动检测等
3. 专属 provider ID — 如 deepseek、anthropic、kimi-coding

非一等提供商（如 SenseNova、LongCat、Together AI）则需要通过 custom_providers: 自定义配置。

对比示例：

# ✅ DeepSeek 是一等提供商，直接写
model:
  provider: deepseek
  default: deepseek-chat

# ❌ 写成 custom 就多余了，失去了自动处理特殊行为的优势
custom_providers:
  - name: deepseek
    base_url: https://api.deepseek.com/v1
    key_env: DEEPSEEK_API_KEY
model:
  provider: custom:deepseek

以下提供商内置支持，只需设置 API Key 环境变量，不需要 custom_providers:：

一等提供商的标准配置：

model:
  provider: deepseek
  default: deepseek-chat

# .env
DEEPSEEK_API_KEY=sk-xxx

五、故障转移（fallback_providers）

当主模型失败（速率限制、服务器错误、认证失败）时，Hermes 按顺序尝试备用提供商，不丢失对话。

标准写法

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
  - provider: deepseek
    model: deepseek-chat

旧版兼容写法（仍可用）

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

支持的故障转移提供商

openrouter、nous、anthropic、gemini、zai、kimi-coding、kimi-coding-cn、minimax、minimax-cn、deepseek、nvidia、xai、huggingface、alibaba、custom 等。

故障转移行为

• 链按条目逐一尝试
• 每个会话激活一次
• 中途切换模型和提供商，不丢失对话
• 仅通过 config.yaml 或 hermes fallback 配置

六、辅助模型（auxiliary）

即使使用 Nous Portal、Codex 或自定义端点，某些工具（视觉、网页摘要、压缩等）仍使用单独的"辅助"模型。

默认行为

默认 provider: auto，Hermes 将辅助任务路由到主聊天模型。

自定义辅助模型

auxiliary:
  vision:
    provider: custom:sensenova
    model: sensenova-6.7-flash-lite
    timeout: 120
  web_extract:
    provider: auto
    timeout: 360
  compression:
    provider: auto
    timeout: 120

辅助任务列表

七、上下文长度检测机制

Hermes 使用多源解析链检测上下文窗口：

1. 配置覆盖 — config.yaml 中的 model.context_length（最高优先级）
2. 自定义提供商按模型 — custom_providers[].models.<id>.context_length
3. 持久缓存 — 之前发现的值（重启后保留）
4. 端点 /models — 查询服务器 API
5. OpenRouter API — 实时模型元数据
6. models.dev — 社区维护的注册表
7. 回退默认值 — 默认 128K

同一模型在不同服务商处可能有不同的上下文限制。例如 claude-opus-4.6 在 Anthropic 直连时为 1M，在 GitHub Copilot 上为 128K。

八、常见错误与避坑

错误 1：provider 值写错

# ❌ 错误
provider: sensenova

# ✅ 正确（自定义提供商用 custom: 前缀）
provider: custom:sensenova

错误 2：key_env 拼写错误

# ❌ 错误——.env 里找不到这个变量
key_env: SENSENOVA_API_KEYS

# ✅ 正确
key_env: SENSENOVA_API_KEY

错误 3：context_length 设置过小

智能体使用至少需要 16k–32k 上下文。系统 prompt 加工具 schema 就可能占用 4k–8k tokens。

# ❌ 太小
context_length: 4096

# ✅ 推荐
context_length: 131072

错误 4：一等提供商误用 custom_providers

DeepSeek、阿里 DashScope 等一等提供商不需要 custom_providers:，直接写 provider: 即可：

# ❌ 多余
custom_providers:
  - name: deepseek
    base_url: https://api.deepseek.com/v1
    key_env: DEEPSEEK_API_KEY

model:
  provider: custom:deepseek

# ✅ 正确
model:
  provider: deepseek
  default: deepseek-chat

错误 5：base_url 末尾缺少 /v1

# ❌ 缺少 /v1
base_url: https://token.sensenova.cn

# ✅ 正确
base_url: https://token.sensenova.cn/v1

九、hermes model 与 /model 的区别

想切换到尚未配置的提供商，必须退出会话（Ctrl+C 或 /quit），运行 hermes model，完成配置后再开新会话。

十、完整配置示例

一个典型的多提供商 + 故障转移 + 辅助模型配置：

model:
  default: sensenova-6.7-flash-lite
  provider: custom:sensenova
  base_url: https://token.sensenova.cn/v1

custom_providers:
  - name: SENSENOVA
    base_url: https://token.sensenova.cn/v1
    key_env: SENSENOVA_API_KEY
    models:
      sensenova-6.7-flash-lite:
        context_length: 128000
      deepseek-v4-flash:
        context_length: 1000000
  - name: LongCat
    base_url: https://api.longcat.chat/openai
    key_env: LONGCAT_API_KEY
    models:
      LongCat-2.0-Preview:
        context_length: 1000000
        max_output_tokens: 128000

fallback_providers:
  - provider: custom:LongCat
    model: LongCat-2.0-Preview

auxiliary:
  vision:
    provider: custom:sensenova
    model: sensenova-6.7-flash-lite
    timeout: 120
  web_extract:
    provider: auto
    timeout: 360
  compression:
    provider: auto
    timeout: 120

对应 .env：

SENSENOVA_API_KEY=sk-xxx
LONGCAT_API_KEY=sk-xxx

总结

配置文件是 Hermes 行为的核心。理解 model → custom_providers → fallback_providers → auxiliary 这四层结构，就能覆盖 99% 的使用场景。