Hermes Agent 原理与实战——第5章模型供应商与配置

Hermes Agent 将"模型"做成了可热插拔的运行时组件。你可以用 hermes model 在 200 多个模型之间任意切换，也可以为不同任务配置不同的模型与不同的 fallback 链；同时凭据可以集中管理、复用密钥池。

本章从Model Provider 抽象入手，逐层深入三种 API 模式、Fallback 故障切换、Credential Pool 密钥轮询、Auxiliary Client 辅助模型、Provider Routing 的配置，帮助你构建一套高可用、低成本、易维护的多模型调度体系。

5.1 Model Provider 抽象：模型统一接口

Hermes 在运行时提供了一层完整的 Provider（供应商）抽象。它将认证鉴权、端点发现、API 协议适配、模型元数据管理、故障回退以及辅助任务路由等能力全部封装在内。无论底层对接的是 OpenAI、Anthropic、本地 Ollama，还是企业内网的自托管 vLLM，Hermes 的上层均以统一接口与之下交互，完全屏蔽底层差异。

一、三种 API 模式

Hermes 内部统一支持三种 API 模式。

API 模式	适用场景	客户端实现	典型供应商
`chat_completions`	绝大多数 OpenAI 兼容端点、事实标准	`openai.OpenAI`	OpenRouter、DeepSeek、GLM、Kimi、vLLM、Ollama 等 99% 的供应商
`codex_responses`	OpenAI Codex / Responses API	`openai.OpenAI`（Responses 格式）	OpenAI Codex
`anthropic_messages`	Anthropic 原生 Messages API	`anthropic.Anthropic`（带 adapter）	Anthropic、MiniMax Anthropic 兼容端点

模式解析顺序：

显式 api_mode 参数指定（最高优先级）
Provider 特定检测（如 anthropic → anthropic_messages）
Base URL 启发式规则（如 api.anthropic.com → anthropic_messages）
默认：chat_completions

模式决定了消息的格式化方式、工具调用的结构、响应的解析方式，以及缓存/流式传输的工作方式。三种模式在 API 调用前后均收敛到相同的内部消息格式（OpenAI 风格的 role/content/tool_calls dict）。

二、运行时解析的输出

无论上游来源如何，解析器最终都输出一个统一结构的字典：

1
2
3
4
5
6
7
8


{
    "provider": "your-provider",      # Provider ID
    "api_mode": "chat_completions",   # 线路协议
    "base_url": "https://...",        # 推理端点
    "api_key": "...",                 # 认证密钥
    "source": "env|portal|auth-store|explicit",  # 来源标记
    # ...Provider 特定的元数据（过期/刷新信息等）
}

这套输出被以下所有场景共享：hermes chat CLI、Gateway 消息处理、在全新会话中运行的 Cron 任务、ACP 编辑器会话、辅助模型任务。这意味着你只需配置一次，全链路生效。

三、运行时解析优先级

当 Hermes 需要确定"当前用哪个 Provider、哪个模型、哪种 API 模式"时，运行时解析器按以下严格顺序决策（优先级从高到低）：

显式 CLI/运行时请求 —— 例如 hermes chat --model anthropic/claude-opus-4。
~/.hermes/config.yaml 中的模型/Provider 配置 —— 用户持久化保存的选择。
环境变量 —— OPENROUTER_API_KEY、ANTHROPIC_API_KEY 等。
Provider 特定的默认值或自动解析 —— 内置安全兜底。

这个顺序非常重要：已保存的 config.yaml 被视为正常运行的真实来源，可以防止过时的 shell 导出变量悄悄覆盖用户在 hermes model 中最后选择的端点。

5.2 官方支持的模型供应商

截至当前版本，Hermes 内置支持以下 Provider。它不仅覆盖了主流国际供应商，还原生覆盖了中国区主流供应商，这对中文开发者极为友好。

Provider	说明	配置入口
Nous Portal	Nous Research 自家订阅服务，零配置	通过 `hermes model` 进行 OAuth 登录
OpenAI Codex	ChatGPT 账号体系，Codex/Responses 模型	通过 `hermes model` 进行设备码认证
Anthropic	Claude 全系；Max 订阅可走 OAuth	OAuth 或 `ANTHROPIC_API_KEY`
OpenRouter	统一路由 200+ 模型	`OPENROUTER_API_KEY`
Z.AI / GLM	智谱 GLM	`GLM_API_KEY` / `ZAI_API_KEY`
Kimi / Moonshot	Moonshot 国际版	`KIMI_API_KEY`
Kimi / Moonshot China	Moonshot 中国区端点	`KIMI_CN_API_KEY`
Arcee AI	Trinity 系列	`ARCEEAI_API_KEY`
GMI Cloud	多模型直 API	`GMI_API_KEY`
MiniMax (OAuth)	通过浏览器 OAuth 使用 MiniMax-M2.7，无需 API key	`hermes model` → MiniMax (OAuth)
MiniMax	MiniMax 国际	`MINIMAX_API_KEY`
MiniMax China	MiniMax 中国区	`MINIMAX_CN_API_KEY`
Alibaba Cloud / DashScope	Qwen 全系	`DASHSCOPE_API_KEY`
Hugging Face	通过统一路由器使用 20+ 开源模型（Qwen、DeepSeek、Kimi 等）	`HF_TOKEN`
AWS Bedrock	通过原生 Converse API 使用 Claude、Nova、Llama、DeepSeek	IAM 角色或 `aws configure`
Kilo Code	KiloCode 模型	`KILOCODE_API_KEY`
OpenCode Zen	按量付费精选模型	`OPENCODE_ZEN_API_KEY`
OpenCode Go	月度订阅开放模型	`OPENCODE_GO_API_KEY`
DeepSeek	直接访问 DeepSeek API	`DEEPSEEK_API_KEY`
NVIDIA NIM	Nemotron / 自托管 NIM	`NVIDIA_API_KEY`（可选 `NVIDIA_BASE_URL`）
GitHub Copilot	Copilot 订阅（GPT-5.x、Claude、Gemini 等）	通过 `hermes model` 进行 OAuth，或设置 `COPILOT_GITHUB_TOKEN` / `GH_TOKEN`
GitHub Copilot ACP	Copilot ACP 后端（本地 `copilot` CLI）	`hermes model`（要先 `copilot login`）
Vercel AI Gateway	Vercel AI Gateway 路由	`AI_GATEWAY_API_KEY`
Azure AI Foundry	Azure 模型部署	Azure 凭据
xAI / Grok	xAI Grok 系列	`XAI_API_KEY` 或 xAI OAuth
StepFun	阶跃星辰	`STEPFUN_API_KEY`
Qwen OAuth	通义千问 Portal OAuth	`hermes model` → Qwen OAuth
Xiaomi	小米大模型	`XIAOMI_API_KEY`
Ollama Cloud	Ollama 云服务	`OLLAMA_CLOUD_API_KEY`
Tencent TokenHub	腾讯模型平台	`TENCENT_API_KEY`
Custom Endpoint	vLLM、SGLang、Ollama、LMStudio 等 OpenAI 兼容端点	设置 base URL + API key

关键约束：Hermes 要求模型上下文窗口 ≥ 64K tokens。上下文窗口较小的模型无法为多步骤工具调用工作流维持足够的工作内存，启动时将被拒绝。绝大多数主流模型轻松满足，如果你运行本地模型，请将其上下文大小设置为至少 64K（例如 llama.cpp 使用 --ctx-size 65536，Ollama 使用 -c 65536）。

5.3 配置模型

Hermes 把模型分为**主模型（Main Model）和辅助模型（Auxiliary Model）**两个角色：

主模型 ： agent 的思考核心。每条用户消息、每个工具调用循环、每次流式响应都经由该模型处理。
辅助模型 ： agent 卸载给较小模型的边缘任务。包括上下文压缩、视觉（图像分析）、网页摘要、审批评分、MCP 工具路由、会话标题生成和技能搜索。每项任务有独立槽位，可单独覆盖。

5.3.1 配置主模型

共 4 种配置方式：

1. 交互式切换（推荐）

1

hermes model

Hermes 会列出所有可用 Provider，引导你选择提供商、完成 API Key 输入或 OAuth 授权。选模型时自动过滤掉上下文不足 64K 的型号，避免误选无法运行的模型。选择结果写入 ~/.hermes/config.yaml 的 model.provider 和 model.model 字段。

2. 命令行直接设置

1

hermes config set model anthropic/claude-opus-4.6

直接写入 ~/.hermes/config.yaml，对所有后续会话生效。

3. 会话内临时切换

在任意 hermes chat 会话内：

1
2


/model gpt-5.4 --provider openrouter             # 仅当前会话
/model gpt-5.4 --provider openrouter --global    # 同时持久化到 config.yaml

仅在当前 CLI 或 Gateway 会话中生效，适合临时实验。配合 /retry 可快速对比不同供应商对同一问题的响应差异。

4. 手动编辑配置文件

直接修改 ~/.hermes/config.yaml：

1
2
3
4
5
6


# ~/.hermes/config.yaml
model:
  provider: openrouter
  default: anthropic/claude-opus-4.7
  base_url: ''        # 切换 Provider 时自动清空
  api_mode: chat_completions

5.3.2 辅助模型

Hermes 使用辅助模型处理图像分析、网页摘要、浏览器截图分析、会话标题生成和上下文压缩等附带任务。默认配置（auxiliary.*.provider: "auto"）下，Hermes 将每个辅助任务路由到主聊天模型 ，您无需配置任何内容即可开始。

⚠️ 注意：若主模型为高成本推理模型，辅助任务会显著增加费用。如需固定使用便宜且快速的模型处理附带任务，需显式设置 auxiliary.*.provider 和 auxiliary.*.model（例如，通过 OpenRouter 调用 Gemini Flash 处理视觉和网页提取）。

5.3.2.1 辅助任务清单

Hermes 支持为以下辅助任务独立配置模型：

辅助任务	说明	默认超时
`vision`	图像分析、浏览器截图理解	120s
`web_extract`	网页摘要、浏览器页面文本提取	360s
`compression`	上下文压缩摘要	120s
`approval`	危险命令审批分类器	30s
`skills_hub`	技能中心匹配与搜索	30s
`mcp`	MCP 工具调度	30s
`triage_specifier`	Kanban 分类规格说明器	120s
`title_generation`	会话标题生成	—
`profile_describer`	用户画像描述	—

每个辅助任务默认为 auto，即 Hermes 对该任务使用主模型。当某个边缘任务需要更便宜或更快的模型时，可单独覆盖该槽位。

5.3.2.2 通用配置模式

Hermes 中的每个模型槽位 —— 辅助任务、压缩、回退 —— 使用相同的三个键：

键	作用	默认值
`provider`	用于认证和路由的 provider	`"auto"`
`model`	请求的模型	provider 的默认值
`base_url`	自定义 OpenAI 兼容端点（覆盖 provider）	未设置

当设置 base_url 时，Hermes 忽略 provider 并直接调用该端点（使用 api_key 或 OPENAI_API_KEY 进行认证）。当仅设置 provider 时，Hermes 使用该 provider 的内置认证和基础 URL。

辅助任务的可用 providers：auto、main，以及provider 注册表中的任何 provider —— openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、gemini、qwen-oauth、zai、kimi-coding、kimi-coding-cn、minimax、minimax-cn、minimax-oauth、deepseek、nvidia、xai、xai-oauth、ollama-cloud、alibaba、bedrock、huggingface、arcee、xiaomi、kilocode、opencode-zen、opencode-go、azure-foundry —— 或您 custom_providers 列表中任何命名的自定义 provider（例如 provider: "beans"）。

5.3.2.2 配置辅助模型

一、命令行交互式

无需手动编辑 YAML，运行 hermes model 并从菜单中选择**“配置辅助模型”**。即可获得交互式的每任务选择器：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


$ hermes model
→ Configure auxiliary models

[ ] vision               currently: auto / main model
[ ] web_extract          currently: auto / main model
[ ] title_generation     currently: openrouter / google/gemini-3-flash-preview
[ ] compression          currently: auto / main model
[ ] approval             currently: auto / main model
[ ] triage_specifier     currently: auto / main model
[ ] kanban_decomposer    currently: auto / main model
[ ] profile_describer    currently: auto / main model

选择任务 → 选择 Provider（OAuth 流程会自动打开浏览器；API Key Provider 会提示输入）→ 选择模型。更改会自动持久化到 config.yaml 的 auxiliary.<task>.* 路径下，与主模型选择器相同的机制。

二、手动编辑配置文件

直接写入 ~/.hermes/config.yaml，完整辅助配置参考：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65


# ~/.hermes/config.yaml
auxiliary:
  # 图像分析（vision_analyze 工具 + 浏览器截图）
  vision:
    provider: "auto"           # "auto"、"openrouter"、"nous"、"codex"、"main" 等
    model: ""                  # 例如 "openai/gpt-4o"、"google/gemini-2.5-flash"
    base_url: ""               # 自定义 OpenAI 兼容端点（覆盖 provider）
    api_key: ""                # base_url 的 API 密钥（回退到 OPENAI_API_KEY）
    timeout: 120               # 秒 —— LLM API 调用超时；视觉负载需要宽裕的超时
    download_timeout: 30       # 秒 —— 图像 HTTP 下载；慢速连接请增加

  # 网页摘要 + 浏览器页面文本提取
  web_extract:
    provider: "auto"
    model: ""                  # 例如 "google/gemini-2.5-flash"
    base_url: ""
    api_key: ""
    timeout: 360               # 秒（6 分钟）—— 每次尝试的 LLM 摘要

  # 危险命令审批分类器
  approval:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30                # 秒

  # 上下文压缩超时（与 compression.* 配置分开）
  compression:
    timeout: 120               # 秒 —— 压缩摘要长对话，需要更多时间
    # fallback_chain:           # 可选 —— 发生速率限制/连接故障时尝试的 provider
    #   - provider: nous
    #     model: deepseek/deepseek-chat
    #   - provider: openrouter
    #     model: google/gemini-2.5-flash
    #     base_url: ""
    #     api_key: ""

  # 技能中心 —— 技能匹配和搜索
  skills_hub:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # MCP 工具调度
  mcp:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # Kanban 分类规格说明器 —— `hermes kanban specify <id>`（或
  # 仪表板上 Triage 列卡片的 ✨ Specify 按钮）使用此
  # 槽位将单行描述扩展为具体规格并将
  # 任务提升到 `todo`。便宜快速的模型在这里效果很好；规格扩展
  # 很短，不需要推理深度。
  triage_specifier:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 120

**提示：**每个辅助任务都有可配置的 timeout（秒）。默认值：vision 120s、web_extract 360s、approval 30s、compression 120s。如果您为辅助任务使用慢速本地模型，请增加这些值。Vision 还有单独的 download_timeout（默认 30s）用于 HTTP 图像下载 —— 对于慢速连接或自托管图像服务器，请增加此值。

5.3.3 辅助任务回退链

每个辅助任务都可以独立配置 fallback_chain，当主要辅助 Provider 因限流、网络故障或付费限制失败时自动切换：

1
2
3
4
5
6
7
8
9


auxiliary:
  compression:
    provider: openrouter
    model: openai/gpt-4o-mini
    fallback_chain:
      - provider: nous
        model: deepseek/deepseek-chat
      - provider: openrouter
        model: google/gemini-2.5-flash

切换逻辑：跳过与已失败 Provider 相同的条目，依次尝试剩余条目，直到成功或链耗尽。如果所有回退都失败，Hermes 会回退到主 Agent 模型作为最终安全网。

5.3.4 Provider Routing：精细化路由

OpenRouter 提供了 Provider Routing 能力，Hermes 将其一等公民化，让你可以控制请求到底走哪一家底层供应商。

1
2
3
4
5
6
7


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

这一节最常见的用法：

想省钱：sort: price；
想快：sort: latency；
不想被某地区供应商路由：avoid: [...]。
只信任特定供应商 prefer: [anthropic, openai]

5.3.5 辅助任务中的 Provider Routing

当辅助任务解析到 OpenRouter 时，主 Agent 的 provider_routing 和 openrouter.min_coding_score 不会自动传播——按设计，每个辅助任务是独立的。如需为特定辅助任务设置路由偏好，通过 extra_body 按任务配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


auxiliary:
  compression:
    provider: openrouter
    model: openrouter/pareto-code
    extra_body:
      provider:
        order: [anthropic, google]
        sort: throughput
      plugins:
        - id: pareto-router
          min_coding_score: 0.5

形状与 OpenRouter 在聊天请求体中接受的内容一致。Hermes 原样转发整个 extra_body。

5.4 上下文压缩

当对话长度接近模型上下文上限时，Hermes 会自动压缩历史消息。压缩由独立的 LLM 调用完成，你可以指定任意 provider 或端点来处理。

所有压缩相关配置均在 config.yaml 中管理，不支持环境变量。

完整参考配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# ~/.hermes/config.yaml
compression:
  enabled: true                                     # 开启/关闭压缩
  threshold: 0.50                                   # 在上下文限制的此百分比时压缩
  target_ratio: 0.20                                # 保留为最近尾部的阈值分数
  protect_last_n: 20                                # 保持未压缩的最少最近消息数
  hygiene_hard_message_limit: 5000                  # Gateway 安全阀 —— 见下文

# 摘要模型/provider 在 auxiliary: 下配置：
auxiliary:
  compression:
    model: ""                                       # 空 = 使用主聊天模型。覆盖为例如 "google/gemini-3-flash-preview" 以获得更便宜/更快的压缩。
    provider: "auto"                                # Provider："auto"、"openrouter"、"nous"、"codex"、"main" 等
    base_url: null                                  # 自定义 OpenAI 兼容端点（覆盖 provider）

5.5 上下文引擎

上下文引擎控制在接近模型 token 限制时如何管理对话。内置的 compressor 引擎使用有损摘要。插件引擎可以用替代策略替换它。

内置引擎：compressor，采用有损摘要策略。
插件引擎：由第三方插件提供替代策略（如无损上下文管理）。

配置方式：

使用内置压缩（默认）

1
2


context:
  engine: "compressor"

使用插件引擎（如 LCM 无损上下文管理）

1
2


context:
  engine: "lcm"    # 必须与插件注册名称完全一致

⚠️ 重要：插件引擎不会自动激活。即使已安装插件，也必须将 context.engine 显式设置为插件名称才能启用。可用引擎可以通过 hermes plugins → Provider Plugins → Context Engine 浏览和选择。

5.6 迭代预算

当 agent 在处理具有许多工具调用的复杂任务时，它可能会耗尽其迭代预算（默认：90 轮）。Hermes 不会在任务中途注入压力警告 —— 早期版本会在预算达到 70%/90% 时警告模型，这会导致模型过早放弃复杂任务，该机制已于 2026 年 4 月移除。

取而代之的是，当预算真正耗尽（90/90）时，Hermes 注入一条消息要求模型收尾，并允许一次宽限调用以便其给出最终响应。如果该宽限调用仍未产生文本，则会要求 agent 总结已完成的工作。

1
2
3


agent:
  max_turns: 90                # 每次对话轮次的最大迭代次数（默认：90）
  api_max_retries: 3           # 回退启动前每个 provider 的重试次数（默认：3）

当迭代预算完全耗尽时，CLI 向用户显示通知：⚠ Iteration budget reached (90/90) — response may be incomplete。

agent.api_max_retries 控制 Hermes 在回退 provider 切换启动之前对瞬时错误（速率限制、连接断开、5xx）重试 provider API 调用的次数。默认为 3 —— 总共四次尝试。如果配置了[回退 providers]并希望更快地故障转移，请将其降至 0，这样主 provider 上的第一个瞬时错误会立即切换到回退，而不是对不稳定的端点进行重试。

5.7 API 超时

Hermes 对流式和非流式调用分别管理超时。针对本地 Provider（如 Ollama、vLLM、LM Studio），系统会自动放宽部分限制，避免大上下文预填充时的误杀。

超时类型	默认值	环境变量 / 配置路径	本地 Provider 行为
Socket 读取	120s	`HERMES_STREAM_READ_TIMEOUT`	自动提升至 1800s
流式无响应检测	180s	`HERMES_STREAM_STALE_TIMEOUT`	自动禁用
非流式无响应检测	300s	`HERMES_API_CALL_STALE_TIMEOUT` `providers.<id>.stale_timeout_seconds`	保持默认时自动禁用
非流式 API 调用	1800s	`HERMES_API_TIMEOUT` `providers.<id>.request_timeout_seconds`	不变

各项说明：

Socket 读取超时：控制等待 Provider 下一个数据块的最大间隔。本地 LLM 在大上下文预填充时可能数分钟无输出，因此检测到本地端点时自动放宽至 30 分钟。显式设置 HERMES_STREAM_READ_TIMEOUT 时，无论是否本地端点，一律使用设定值。
流式无响应检测（Stale Stream）：用于终止只发送 SSE keep-alive ping、但长期无实际内容的连接。本地 Provider 在预填充期间通常不发送 keep-alive，因此该检测自动禁用。
非流式无响应检测（Stale Non-stream）：终止长时间没有响应的非流式调用。默认情况下，Hermes 在本地端点上禁用此功能，以避免长时间预填充期间的误报。如果您显式设置 providers.<id>.stale_timeout_seconds、providers.<id>.models.<model>.stale_timeout_seconds 或 HERMES_API_CALL_STALE_TIMEOUT，即使在本地端点也会生效。

5.8 上下文压力警告

独立于迭代预算之外，上下文压力用于监测对话长度接近压缩阈值的程度——即触发上下文压缩、对旧消息进行摘要的临界点。这让用户和 agent 都能及时感知对话膨胀状态。

进度	级别	发生的事情
≥ 60% 到阈值	信息	CLI 显示青色进度条；gateway 发送信息通知
≥ 85% 到阈值	警告	CLI 显示粗体黄色进度条；gateway 警告压缩即将发生

在 CLI 中，上下文压力在工具输出流中显示为进度条：

1

  ◐ context ████████████░░░░░░░░ 62% to compaction  48k threshold (50%) · approaching compaction

在消息平台上，发送纯文本通知：

1

◐ Context: ████████████░░░░░░░░ 62% to compaction (threshold: 50% of window).

如果自动压缩被禁用，警告会告诉您上下文可能被截断。

上下文压力完全自动运行，无需配置。它仅作为面向用户的可视化提示，不修改消息流，也不会向模型上下文注入任何内容。

5.9 凭据池策略

当团队多人共享同一份 API Key 配额，或单 Key 触发频率限制时，Credential Pool（凭据池）可以让多个密钥按策略轮询使用，显著提升可用性。

策略存储在 config.yaml 中：

1
2
3
4


# ~/.hermes/config.yaml
credential_pool_strategies:
  openrouter: round_robin    # 均匀循环使用密钥
  anthropic: least_used      # 始终选择使用最少的密钥

策略	行为
`fill_first`（默认）	持续使用第一个健康密钥直至耗尽，然后切换到下一个
`round_robin`	均匀循环遍历所有密钥，每次选择后轮换
`least_used`	始终选择请求次数最少的密钥
`random`	在健康密钥中随机选择

凭据池存储在 ~/.hermes/auth.json 的 credential_pool 键下（而非 config.yaml）：：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


{
  "version": 1,
  "credential_pool": {
    "openrouter": [
      {
        "id": "abc123",
        "label": "OPENROUTER_API_KEY",
        "auth_type": "api_key",
        "priority": 0,
        "source": "env:OPENROUTER_API_KEY",
        "access_token": "sk-or-v1-...",
        "last_status": "ok",
        "request_count": 142
      }
    ]
  },
}

5.10 Prompt 缓存

Hermes 在支持的 Provider 上自动启用跨会话 Prompt 缓存，无需任何配置。

对于原生 Anthropic、OpenRouter 和 Nous Portal 上的 Claude，Hermes 会在系统提示词和技能块上插入 cache_control 断点，TTL 设为 1 小时：

首次发送（一小时内）：按完整输入费率计费。
后续发送（同一小时内）：按折扣缓存读取费率计费，从缓存中直接提取.

这意味着系统提示词、已加载的技能内容以及长上下文的早期部分，在首个小时内可被同一用户的所有 hermes 会话及分叉子 agent 复用。

不同Provider 差异：

Provider	TTL	说明
Anthropic（原生）	1h	标准行为
OpenRouter	1h	标准行为
Nous Portal	1h	标准行为
Qwen Cloud（DashScope）	5min	Qwen Cloud（阿里DashScope）上游将缓存 TTL 限制为 5 分钟，因此 Hermes 在那里使用 5 分钟断点 TTL。
AWS Bedrock / Azure Foundry	Provider 默认值	回退至平台自带缓存策略
xAI Grok	会话级	使用对话 ID 固定机制，详见 xAI 文档

Prompt 缓存始终开启，不设关闭开关。即使在单轮对话中也能降低成本——系统提示词通常占输入 token 的相当比例，缓存后可显著节省费用。

5.11 自定义 OpenAI 兼容端点

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

命令行交互式配置：

1
2
3
4
5


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

写入 config.yaml 后大致是：

1
2
3
4
5
6
7


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.12 完整模型相关配置示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90


# ~/.hermes/config.yaml
model:
  default: deepseek-v4-pro
  provider: deepseek
  base_url: https://api.deepseek.com/v1

agent:
  max_turns: 150
  verbose: false
  reasoning_effort: medium
  api_max_retries: 3  

compression:
  enabled: true
  threshold: 0.5
  target_ratio: 0.2
  protect_last_n: 20
  max_attempts: 3
  protect_first_n: 3
  codex_gpt55_autoraise: true
  codex_app_server_auto: native
  idle_compact_after_seconds: 0
prompt_caching:
  cache_ttl: 5m
  
# 辅助模型配置
auxiliary:
  # 图像分析（vision_analyze 工具 + 浏览器截图）
  vision:
    provider: "auto"           # "auto"、"openrouter"、"nous"、"codex"、"main" 等
    model: ""                  # 例如 "openai/gpt-4o"、"google/gemini-2.5-flash"
    base_url: ""               # 自定义 OpenAI 兼容端点（覆盖 provider）
    api_key: ""                # base_url 的 API 密钥（回退到 OPENAI_API_KEY）
    timeout: 120               # 秒 —— LLM API 调用超时；视觉负载需要宽裕的超时
    download_timeout: 30       # 秒 —— 图像 HTTP 下载；慢速连接请增加

  # 网页摘要 + 浏览器页面文本提取
  web_extract:
    provider: "auto"
    model: ""                  # 例如 "google/gemini-2.5-flash"
    base_url: ""
    api_key: ""
    timeout: 360               # 秒（6 分钟）—— 每次尝试的 LLM 摘要

  # 危险命令审批分类器
  approval:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30                # 秒

  # 上下文压缩超时（与 compression.* 配置分开）
  compression:
    timeout: 120               # 秒 —— 压缩摘要长对话，需要更多时间
    # fallback_chain:           # 可选 —— 发生速率限制/连接故障时尝试的 provider
    #   - provider: nous
    #     model: deepseek/deepseek-chat
    #   - provider: openrouter
    #     model: google/gemini-2.5-flash
    #     base_url: ""
    #     api_key: ""

  # 技能中心 —— 技能匹配和搜索
  skills_hub:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # MCP 工具调度
  mcp:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # Kanban 分类规格说明器 —— `hermes kanban specify <id>`（或
  # 仪表板上 Triage 列卡片的 ✨ Specify 按钮）使用此
  # 槽位将单行描述扩展为具体规格并将
  # 任务提升到 `todo`。便宜快速的模型在这里效果很好；规格扩展
  # 很短，不需要推理深度。
  triage_specifier:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 120

.env 里同时放：

1
2
3


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

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

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

5.14 本章小结

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

三种 API 模式 + 自动检测，让同一份 Agent 代码无感跑遍 Anthropic / OpenAI / Codex / OpenAI-Compatible 全生态；
Provider Registry + 运行时解析器，将凭据、端点、协议、模型元数据全部集中管理，CLI / Gateway / Cron / ACP / 辅助任务全链路共享；
主 / 辅模型分离（Auxiliary Client），把昂贵的旗舰模型留给真正需要的对话，便宜的模型承担视觉、摘要、压缩等后台搬砖任务；
Fallback + Provider Routing + Credential Pool，把"模型挂了"变成自愈过程，把"单 Key 限流"变成轮询负载均衡；
OAuth 与自定义端点，让你既可以零配置上车 Nous Portal，也可以挂自己机房的 vLLM；
/model 即时切换、/usage 即时审计，工程师手感舒适，生产环境可控。