第五章：模型供应商与配置体系

Hermes Agent 最显著的工程优势之一，是它把”模型”做成可热插拔的运行时：你可以用 hermes model 在 200+ 模型之间任意切换，也可以为不同任务配置不同模型与不同 fallback 链；同时凭据可以集中管理、复用密钥池。本章把这一切讲透。

5.1 三种 API 模式回顾

第二章已经介绍过，Hermes 内部统一支持三种 API 模式：

模式选择优先级：

1. 你显式传入 api_mode；
2. 根据 Provider 自动检测（anthropic → anthropic_messages）；
3. base URL 启发式（api.anthropic.com → anthropic_messages）；
4. 默认 chat_completions。

三种模式只是”运输方式”不同，Hermes 内部统一为 OpenAI 风格 role/content/tool_calls 字典，你可以无感切换。

5.2 全部官方支持的供应商

下面是当前文档（截至撰稿时）声明支持的 Provider 列表。可以看到 Hermes 不仅覆盖了主流国际供应商，还原生覆盖了主流中国区供应商——这对中文用户极为友好。

关键事实：Hermes 要求模型 上下文窗口 ≥ 64K tokens。绝大多数主流模型轻松满足；本地模型请把 --ctx-size 65536（llama.cpp）或 -c 65536（Ollama）加上。

5.3 选模型的几条简单原则

为不让你陷入选择障碍，先给一份清单。

• 追求最强代码 / Agent 工具调用：Claude 4 / 4.5 / 4.6 系列、GPT-5 系列、Gemini 2.5 Pro、Hermes 系列、Kimi K2 长上下文版本、Qwen3-Coder、DeepSeek V3。
• 追求性价比：DeepSeek、Kimi K2 国际、Qwen Max、Hermes 4，OpenRouter 上挑一个 mid-tier。
• 追求中文工作流：GLM-4.6 / Kimi K2 / Qwen Max / MiniMax M2，配合中国区端点。
• 本地隐私优先：通过 Ollama / vLLM / LMStudio 自托管 Qwen3-Coder、DeepSeek-R1-Distill、Hermes 等。
• 想让 Hermes 永远在线、不操心：Nous Portal 订阅 + Nous Tool Gateway（自带 web search / 图像 / TTS / 浏览器，无须额外密钥）。

hermes model 会把你输入解析成 provider:model_id，比如：

anthropic/claude-opus-4.6
openrouter/openai/gpt-5
deepseek/deepseek-chat
glm/glm-4.6
moonshot/moonshot-v1-128k
custom/<base_url>/<model_name>

5.4 切模型的三种方式

5.4.1 交互式

hermes model

会列出可用 Provider，引导你输入 Key 或走 OAuth；选模型时会自动过滤掉上下文不足 64K 的型号。

5.4.2 命令行直接设

hermes config set model anthropic/claude-opus-4.6

写入 ~/.hermes/config.yaml。

5.4.3 会话内 /model

/model openrouter/openai/gpt-5

只对当前会话生效，方便临时实验。

5.5 主对话模型 vs 辅助模型

Hermes 把模型分成两个角色，避免”用旗舰模型干小事”：

model: anthropic/claude-opus-4.6              # 主：参与所有对话
auxiliary_model: openrouter/openai/gpt-5-mini # 辅：视觉描述、长会话压缩、跨会话摘要
vision_model: openrouter/openai/gpt-4o        # 视觉（可选，单独覆盖）

辅助模型通常便宜很多，但要求”足够能写摘要、读图”。建议：

• 主：你舍得花钱、长上下文、强工具调用的旗舰；
• 辅：GPT-5-mini / Claude Haiku / DeepSeek-Chat / Qwen Max / Kimi K2 中任选一款。

5.6 Fallback Providers：把”挂了”变”换一家”

主 Provider 限流、5xx、网络异常都会触发 Fallback：

fallback_models:
  - openrouter/anthropic/claude-3.5-sonnet
  - openrouter/openai/gpt-5
  - deepseek/deepseek-chat
fallback_strategy: ordered          # ordered / random / cheapest_first
fallback_on:
  - rate_limit
  - server_error
  - timeout
  - validation_error

视觉、压缩等辅助任务有独立 fallback：

auxiliary_fallback_models:
  - openrouter/openai/gpt-5-mini
  - openrouter/anthropic/claude-3.5-haiku

故障切换是透明的：模型对话历史会被 Hermes 复制并交给下一家。详见 user-guide/features/fallback-providers.md。

5.7 Provider Routing：精细化路由

OpenRouter 提供 routing 能力，Hermes 把它一等公民化：

provider_routing:
  prefer:
    - anthropic
    - openai
  avoid:
    - replicate
  sort: throughput     # throughput / latency / price

这一节最常见的用法：

• 想省钱：sort: price；
• 想快：sort: latency；
• 不想被某地区供应商路由：avoid: [...]。

5.8 Credential Pool：多密钥轮询

同一家 Provider 配多把 Key，Hermes 会按策略轮询：

credential_pools:
  openrouter:
    keys: [sk-or-aaa, sk-or-bbb, sk-or-ccc]
    strategy: round_robin       # round_robin / weighted / least_recent
    on_rate_limit: rotate
    cooldown_seconds: 60

适用场景：

• 团队多人共享同一份 API Key 配额；
• 单 Key 触发限流；
• 想让多个 Hermes Profile 各占不同 Key。

5.9 自定义 OpenAI 兼容端点

最常见的就是接 vLLM / SGLang / Ollama / LMStudio：

hermes model
# 选 "Custom Endpoint"
# Base URL: http://192.168.1.2:11434/v1
# API Key: ollama
# Model: qwen3-coder:latest

写入 config.yaml 后大致是：

model: custom/qwen3-coder:latest
custom_endpoints:
  default:
    base_url: http://192.168.1.2:11434/v1
    api_key_env: OLLAMA_API_KEY
    api_mode: chat_completions
    context_length: 131072

提示：本地模型上下文一定要 ≥ 64K，否则 Hermes 启动时直接报错。Ollama 用 -c 65536，vLLM 启动时加 --max-model-len 131072。

5.10 OAuth 类供应商的最佳实践

部分 Provider 支持 OAuth（Nous Portal、Anthropic Max、OpenAI Codex、MiniMax、GitHub Copilot）。共同点：

• 第一次 hermes model → 选 OAuth Provider，会打开浏览器 / 设备码；
• Refresh Token 存到 ~/.hermes/.env，过期会自动刷新；
• 退出 / 撤销：hermes auth logout <provider>。

特别提醒：

• Anthropic OAuth 仅 Max 订阅可用，普通 Pro 不能走；
• GitHub Copilot ACP 走的是本地 copilot CLI，需要先 copilot login；
• MiniMax OAuth 走浏览器，国内开发者建议优先尝试，省去申请 API Key 的繁琐。

5.11 完整配置示例（推荐起步模板）

# ~/.hermes/config.yaml

# ── 主 / 辅模型 ────────────────────────────────────
model: anthropic/claude-opus-4.6
auxiliary_model: openrouter/openai/gpt-5-mini
vision_model: openrouter/openai/gpt-4o

# ── Fallback ─────────────────────────────────────
fallback_models:
  - openrouter/anthropic/claude-3.5-sonnet
  - openrouter/openai/gpt-5
  - deepseek/deepseek-chat
fallback_strategy: ordered
fallback_on: [rate_limit, server_error, timeout]

# ── Provider Routing ─────────────────────────────
provider_routing:
  prefer: [anthropic, openai]
  avoid: [replicate]
  sort: throughput

# ── 凭据池 ───────────────────────────────────────
credential_pools:
  openrouter:
    keys: [sk-or-aaa, sk-or-bbb]
    strategy: round_robin
    on_rate_limit: rotate

# ── 上下文管理 ────────────────────────────────────
context:
  compress_threshold: 0.5
  hard_compress_threshold: 0.8

# ── 终端后端（详见第六章） ─────────────────────────
terminal:
  backend: docker
  docker:
    image: ghcr.io/nousresearch/hermes-sandbox:latest
    read_only: true

.env 里同时放：

ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
DEEPSEEK_API_KEY=sk-...

5.12 国内开发者实战建议

如果你主要在国内/中文场景使用 Hermes：

• 主：GLM-4.6（智谱）/ Kimi K2 / Qwen-Max；这三家都支持工具调用且上下文 ≥ 128K；
• 辅：DeepSeek-Chat（极便宜，足够做摘要 / 视觉描述（V3 多模态版本））；
• Fallback：OpenRouter 配 Anthropic / OpenAI 兜底（如果有外网）；
• 凭据池：把同公司多人 Key 放一起，防止一人触发限流就影响所有人；
• Tool Gateway 替代品：用 Bing API 或 Tavily 做 web 搜索；本地 Edge TTS 做免费 TTS。

OpenRouter 在国内访问可能不稳，可以考虑加 HTTP 代理（Hermes 全部基于 httpx/openai-python，标准 HTTPS_PROXY/HTTP_PROXY 环境变量都能透传）。

5.13 切换模型的 5 个高频小技巧

1. 想试某个新模型一次：/model openrouter/x-ai/grok-4，不用关 TUI。
2. 想快速比较两家：/retry 后再 /model 切到另一家，再 /retry，直接对比响应。
3. 临时全开 reasoning 模式：用支持 thinking 的模型并 /reasoning 打开。
4. 跨会话固定但单会话覆盖：config.yaml 设默认；/model 临时覆盖。
5. 想看 Provider 实际用了哪一家：/usage 输出会展示当次实际命中的 provider/model 与 fallback 历史。

5.14 Trouble shooting

5.15 本章小结

Hermes 在”模型层”提供了远超普通 Agent 的工程能力：

• 三种 API 模式 + 自动检测，让一份 Agent 代码跑遍 Anthropic / OpenAI / Codex 生态；
• Provider Registry + 凭据集中管理，覆盖国内外主流供应商；
• 主 / 辅模型分离，把贵的留给真正需要的对话，便宜的留给后台搬砖；
• Fallback + Provider Routing + Credential Pool，把”模型挂了”变成自愈过程；
• OAuth 与自定义端点，让你既可以零配置上车 Nous Portal，也可以挂自己机房的 vLLM；
• /model 即时切换、/usage 即时审计，工程师手感舒适。

下一章我们去看另一个解耦层——工具与终端后端。