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 = 单次响应的输出上限。与对话历史长度无关。

三、自定义提供商（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

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

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

/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=***

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

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

核心特点：

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

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

五、故障转移（fallback_providers）

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

标准写法

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

故障转移行为：链按条目逐一尝试、每个会话激活一次、中途切换不丢失对话。

六、辅助模型（auxiliary）

某些工具（视觉、网页摘要、压缩等）使用单独的"辅助"模型。默认 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 使用多源解析链检测上下文窗口：

• 配置覆盖 — config.yaml 中的 model.context_length（最高优先级）
• 自定义提供商按模型 — custom_providers[].models[].context_length
• 持久缓存 — 之前发现的值（重启后保留）
• 端点 /models — 查询服务器 API
• 回退默认值 — 默认 128K

八、常见错误与避坑

错误 1：provider 值写错

# ❌ 错误
provider: sensenova

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

错误 2：context_length 设置过小

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

# ❌ 太小
context_length: 4096

# ✅ 推荐
context_length: 131072

错误 3：一等提供商误用 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

错误 4：base_url 末尾缺少 /v1

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

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

九、hermes model 与 /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=***
LONGCAT_API_KEY=***

总结

理解 model → custom_providers → fallback_providers → auxiliary 这四层结构，就能覆盖 99% 的 Hermes Agent 配置场景。配置文件是 Hermes 行为的核心，正确配置可以提升稳定性和效率。