5. 模型配置：多 Provider 切换

本节目标：搞懂 Hermes Agent 的「主模型 + 辅助模型」双槽位体系，学会用 hermes model 和 /model 在 10+ 个 Provider 之间切换，并理解 Nous Portal、OpenRouter、Bedrock、Ollama 这几条主流路径的差异。学完你能在 5 分钟内把推理后端从云端换到本地，也能让一个便宜的小模型专门负责写会话标题。

两种模型槽位

Hermes Agent 不是「配一个模型就完事」的设计。它把推理需求拆成两类槽位：

主模型（Main model）：智能体思考用的大脑。你的每条消息、每次工具调用循环、每一段流式输出，都走这个模型。
辅助模型（Auxiliary models）：智能体把一些零碎活外包出去的小模型。上下文压缩、图像识别、网页摘要、审批打分、MCP 工具路由、会话标题生成、技能检索，每个任务都有独立槽位，可以单独覆盖。

打个比方，主模型是公司的核心工程师，活儿他全包；辅助模型是外包小工，便宜快，专门干那些不需要顶级智商的杂活——比如给会话起个标题，没必要动用 Opus。

Note

辅助槽位默认是 auto，意思是「跟主模型走」。你只在想省钱或提速时才需要覆盖某个槽位，比如把标题生成交给一个 Flash 模型。

hermes model：交互式切换主模型

切换主模型最标准的姿势是 hermes model 命令。它会启动一个交互式选择器，左边列已认证的 Provider，右边是该 Provider 推荐的模型清单。

hermes model

选完之后，Hermes 把结果写到 ~/.hermes/config.yaml 的 model 段：

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

Note

全新安装时 config.yaml 里的 model: 是个空字符串 ""，这是个「还没配过」的哨兵值。第一次跑 hermes setup 或 hermes model 时，它会被原地升级成上面那个 mapping 结构。如果你看到 config.yaml 里 model: 还是空串，跑一次 hermes model 就会自动改写。

配置文件直接编辑

不喜欢交互式向导的话，直接编辑 ~/.hermes/config.yaml 也行。改完重启读取它的进程即可生效。完整字段定义见第 04 章的配置文件参考。

10+ Provider 全景

Hermes Agent 支持十余个推理 Provider，认证方式各有不同。下面这张表是主流路径的速查：

Provider	认证方式	一句话定位
Nous Portal	OAuth 登录	Nous 自家订阅，一份钱通吃模型 + 工具网关
OpenRouter	API Key	聚合器，一个 Key 通吃 400+ 模型
OpenAI	API Key	GPT 系列，官方直连
Azure OpenAI	Endpoint + Key + API 版本	企业版 OpenAI，走 Azure 部署
AWS Bedrock	IAM（boto3 凭据链）	企业级，Converse API 原生接入
Google Gemini	API Key	Gemini 系列，超长上下文
xAI Grok	OAuth 或 API Key	Grok 系列
Anthropic	OAuth 或 API Key	Claude 系列，直连官方
Ollama	无需 Key（本地）	开源权重模型本地跑，零成本
LM Studio	API Key + Base URL	本地 OpenAI 兼容服务端
Custom Endpoint	自定义	任何 OpenAI 兼容端点

Tip

Provider 在选择器里只显示「已认证」的那些。没认证的不会出现。所以如果你想要的 Provider 不在列表里，先去配置对应的 Key 或跑 OAuth。

Nous Portal：一份订阅，300+ 模型

Nous Portal 是 Nous Research 自己的订阅网关。一次 OAuth 登录，你拿到的不只是模型调用，还有一整套工具网关（网页搜索、图像生成、TTS、浏览器自动化），全部走同一个订阅计费。

最快路径是一行命令：

hermes setup --portal

这一条命令干五件事：

打开浏览器跳到 portal.nousresearch.com 做 OAuth 登录
把 refresh token 存到 ~/.hermes/auth.json
把 model.provider 设成 nous
选一个默认的智能体模型（类似 anthropic/claude-sonnet-4.6）
顺带开启网页搜索、图像生成、TTS、浏览器自动化的工具网关

跑完之后用 hermes portal info 验证一下：

hermes portal info

正常输出长这样：

Nous Portal
───────────
Auth:    ✓ logged in
Portal:  https://portal.nousresearch.com
Model:   ✓ using Nous as inference provider

Tool Gateway
────────────
Web search & extract  via Nous Portal
Image generation      via Nous Portal
Text-to-speech        via Nous Portal
Browser automation    via Nous Portal

Tip

Portal 订阅用户在按量计费的 Provider 上还能再打 9 折。如果你本来就要用 OpenRouter + Firecrawl + FAL + Browserbase 几个后端，一份订阅往往比单买更划算。

别给智能体选 Hermes-4

Portal 上有 Hermes-4-70B 和 Hermes-4-405B，折扣很深。虽然它们支持函数调用和工具使用，但作为通用聊天/推理模型，在多步 Agent 循环的复杂编排场景下，性能可能不如 Claude Sonnet、GPT-5 等专门针对 Agent 场景优化的模型。Hermes-4 适合走订阅代理（subscription-proxy）给非智能体工具用，不适合当 Hermes Agent 的主模型。智能体主模型还是从下面这几个里挑：

/model anthropic/claude-sonnet-4.6     # 通用智能体首选
/model openai/gpt-5.4                  # 强推理 + 工具调用
/model google/gemini-2.5-pro           # 超长上下文
/model deepseek/deepseek-v3.2          # 性价比写码
/model anthropic/claude-opus-4.6       # 硬题重型机

SSH 远程登录的 OAuth 问题

OAuth 需要浏览器，但回调跑在 Hermes 所在的机器上。SSH 登录服务器时，两种解法：

# 方案 A：SSH 端口转发（推荐）
ssh -N -L 8642:127.0.0.1:8642 user@remote-host    # 本地终端开
hermes setup --portal                              # 远程跑，浏览器开打印出来的 URL

# 方案 B：设备码登录（适合 Cloud Shell、Codespaces、EC2 Instance Connect）
hermes auth add nous --type oauth
# 然后再跑 hermes setup --portal 接 Provider + 网关

OpenRouter：聚合器，一个 Key 通吃

OpenRouter 是模型聚合器，一个 API Key 能访问 400+ 模型。Hermes 的选择器会从 OpenRouter 的海量清单里挑出推荐的那批智能体模型给你，不是把 /models 接口的原始 dump 全甩过来。

认证就一行环境变量：

# ~/.hermes/.env
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx

然后 hermes model 选 OpenRouter，挑模型即可。OpenRouter 的模型名带前缀，比如 anthropic/claude-opus-4.7、google/gemini-2.5-flash。

Note

在聚合器上，光秃秃的模型名会先在聚合器内部解析。比如 claude-sonnet-4 在 OpenRouter 上会变成 anthropic/claude-sonnet-4.6，仍然走你的 OpenRouter 认证。但如果你在原生 Anthropic 认证下输 claude-sonnet-4，它就是 claude-sonnet-4-6。如果你发现 Provider 莫名切换了，先检查当前 Provider 是不是你预期的那个。

AWS Bedrock：企业级 IAM 鉴权

Bedrock 走的是原生 Converse API，不是 OpenAI 兼容端点。好处是你能拿到 Bedrock 生态的全部能力：IAM 鉴权、Guardrails、跨区域推理、所有基础模型。

前置条件

AWS 凭据：boto3 凭据链支持的所有来源都行
- IAM 实例角色（EC2/ECS/Lambda，零配置）
- AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY 环境变量
- AWS_PROFILE 走 SSO 或命名 profile
- aws configure 本地开发
boto3 库：装一下
IAM 权限：至少 bedrock:InvokeModel、bedrock:InvokeModelWithResponseStream、bedrock:ListFoundationModels、bedrock:ListInferenceProfiles

Tip

在 EC2/ECS/Lambda 上跑，给计算资源挂一个带 AmazonBedrockFullAccess 的 IAM 角色就行，不用配任何 API Key 和 .env。Hermes 会自动发现实例角色。

配置

跑 hermes model，选「More providers…」→「AWS Bedrock」，选区域和模型。配置完的 config.yaml 长这样：

model:
  default: us.anthropic.claude-sonnet-4-6
  provider: bedrock
  base_url: https://bedrock-runtime.us-east-2.amazonaws.com

bedrock:
  region: us-east-2

区域优先级从高到低：bedrock.region 配置项 > AWS_REGION 环境变量 > AWS_DEFAULT_REGION 环境变量 > 默认 us-east-1。

推理 Profile ID

Bedrock 模型用推理 Profile ID 调用，不是裸模型 ID。带 us. 前缀的走跨区域推理，容量更好、自动故障转移；带 global. 前缀的全球路由。

模型	ID	备注
Claude Sonnet 4.6	`us.anthropic.claude-sonnet-4-6`	推荐，速度能力平衡
Claude Opus 4.6	`us.anthropic.claude-opus-4-6-v1`	最强
Claude Haiku 4.5	`us.anthropic.claude-haiku-4-5-20251001-v1:0`	最快 Claude
Amazon Nova Pro	`us.amazon.nova-pro-v1:0`	亚马逊旗舰
DeepSeek V3.2	`deepseek.v3.2`	开源强模型

Warning

如果你看到「Invocation of model ID … with on-demand throughput isn’t supported」，说明你用了裸模型 ID。换成带 us. 或 global. 前缀的推理 Profile ID 就行。anthropic.claude-sonnet-4-6 是错的，us.anthropic.claude-sonnet-4-6 是对的。

Guardrails

要给所有模型调用套上 Bedrock Guardrails：

bedrock:
  region: us-east-2
  guardrail:
    guardrail_identifier: "abc123def456"  # Bedrock 控制台拿
    guardrail_version: "1"                # 版本号或 "DRAFT"
    stream_processing_mode: "async"       # "sync" 或 "async"
    trace: "disabled"                     # "enabled" / "disabled" / "enabled_full"

Ollama：本地零成本跑模型

Ollama 让你把模型跑在自己机器上，零 API 成本，数据不出本机。Hermes 接 Ollama 走的是 Custom Endpoint 路径，体验跟云端 Provider 一样——终端命令、文件编辑、网页浏览、委托都能用，只是模型在本地推理。

硬件门槛

组件	最低	推荐
内存	8 GB（跑 3B 模型）	32+ GB（跑 27B+ 模型）
存储	5 GB 空闲	30+ GB（多模型）
CPU	4 核	8+ 核
GPU	不强制	NVIDIA 8+ GB VRAM 提速明显

Note
纯 CPU 也能跑。9B 模型在 8 核现代 CPU 上大约 10 tokens/秒。31B 模型纯 CPU 会慢到 2-5 tokens/秒，每个回复 30-120 秒，但能跑。纯 CPU 部署建议把超时拉长：
# ~/.hermes/.env
HERMES_API_TIMEOUT=1800   # 30 分钟

配置步骤

装 Ollama：

curl -fsSL https://ollama.com/install.sh | sh

拉模型（按硬件选）：

ollama pull gemma4:31b    # 24+ GB 内存，支持工具调用，质量最佳

Warning

Hermes 是智能体助手，靠工具调用干活——改文件、跑命令、浏览网页。不支持工具调用的模型只能聊天，不能执行动作。要完整体验，一定选支持工具调用的模型（如 gemma4:31b）。

配置 Hermes（二选一）：

跑 hermes setup，选 Custom Endpoint，填：

Base URL：http://localhost:11434/v1
API Key：留空或填 no-key
Model：gemma4:31b

或者直接改 ~/.hermes/config.yaml：

model:
  default: "gemma4:31b"
  provider: "custom"
  base_url: "http://localhost:11434/v1"

把上下文窗口拉大（关键）：

Ollama 默认 2048 token 上下文，智能体干活至少要 64000 token：

cat > /tmp/Modelfile << 'EOF'
FROM gemma4:31b
PARAMETER num_ctx 64000
EOF

ollama create gemma4-64k -f /tmp/Modelfile

然后把 Hermes 配置里的模型名改成 gemma4-64k。

成本对比

一次典型编码会话（约 100K 输入 + 20K 输出 token）：

Provider	单次成本	月度（每天用）
Anthropic Claude Sonnet	~$0.80	~$24
OpenRouter（GPT-4o）	~$0.60	~$18
Ollama（本地）	$0.00	$0.00

Tip

本地模型扛不住的硬题，可以配个云端 fallback，本地跑 90% 的活，只有本地失败时才打云端付费 API。这块见下一章的 fallback-providers。

辅助模型：11 个任务槽位

点开 Dashboard 的 Models 页，展开 Show auxiliary，你会看到 11 个任务槽位。每个默认是 auto（跟主模型走），可以单独覆盖。

任务	什么时候覆盖
Title Gen（标题生成）	几乎必覆盖。一个 Flash 模型起标题跟 Opus 一样好，便宜 50 倍
Vision（图像识别）	主模型不支持视觉时覆盖，指向 `google/gemini-2.5-flash` 或 `gpt-4o-mini`
Compression（上下文压缩）	用 Opus/M2.7 烧推理 token 做摘要太浪费，快聊模型 1/50 成本搞定
Approval（审批打分）	`approval_mode: smart` 下用便宜模型决定要不要自动批准低风险命令
Web Extract（网页抽取）	重度用 `web_extract` 时覆盖，摘要不需要推理
Skills Hub（技能搜索）	`hermes skills search` 用，通常 `auto` 够
MCP（MCP 工具路由）	通常 `auto` 够
Triage Specifier（看板分流）	`hermes kanban specify` 把一句话扩成具体规格
Kanban Decomposer（看板拆解）	把分流任务拆成子任务图给专家 Profile
Profile Describer（Profile 描述）	`hermes profile describe --auto` 自动生成描述
Curator（技能审查）	跑技能使用审查，推理模型能跑几分钟，便宜模型更划算

覆盖单个任务的 config.yaml 写法：

auxiliary:
  vision:
    provider: openrouter
    model: google/gemini-2.5-flash
    base_url: ''
    api_key: ''
    timeout: 120
    extra_body: {}
    download_timeout: 30

provider: auto + model: '' 表示这个任务跟主模型走，但仍然遵守 fallback 策略。

Note

辅助覆盖不生效的三个排查点：1) 有没有开新会话（老会话不重读配置）；2) provider 是不是设成了 auto（是的话还是用主模型）；3) 该 Provider 有没有认证（没 Key 会回退并报警）。

/model 命令：会话内热切换

hermes model 改的是默认配置，对新会话生效。正在跑的会话不会动。想在当前会话里换模型，用 /model 斜杠命令：

/model gpt-5.4 --provider openrouter             # 只对当前会话
/model gpt-5.4 --provider openrouter --global    # 同时持久化到 config.yaml
/model claude-opus-4.6 --once                    # 只下一回合用，之后自动还原

--global 跟点 Dashboard 的 Change 按钮效果一样，外加把当前会话也切了。

--once 是个很妙的开关——只为这一回合切到贵模型，问完不管成功失败还是中断，下一回合自动还原原来的模型，配置也不持久化。适合「就这一个硬题问一下 Opus」或者「随手一个废问题丢给便宜模型」。

Warning

会话内切模型会重置提示词缓存。提示词缓存是按模型绑定的，任何会话中途换模型——显式 /model、自动 fallback、凭据池轮换——都会让下一条消息按全价输入 token 重读整个对话。长会话里这一次重读的成本，可能比两个模型本身的价差还大。要切就趁早切，或者开新会话再切。
--once 会把提示词缓存前缀打断两次（切出去再切回来）。短会话或便宜→贵的升级场景很划算，但在长会话里随便插一个 side question 可能反而更贵。

model-catalog：模型清单的远程更新

Hermes 给 OpenRouter 和 Nous Portal 维护了一份策展模型清单，托管在文档站上。这样维护者更新推荐列表时不用发新版 hermes-agent。

清单地址：

https://hermes-agent.nousresearch.com/docs/api/model-catalog.json

缓存与回退

清单拉取有完整的容错链：

时机	行为
`/model` 或 `hermes model`	缓存过期才拉，否则用缓存
缓存未过期	不打网络
网络失败但有缓存	静默回退缓存，记一行日志
网络失败且无缓存	静默回退仓库内快照
清单 schema 校验失败	当作不可达处理

缓存位置在 ~/.hermes/cache/model-catalog.json。

配置

model_catalog:
  enabled: true
  url: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
  ttl_hours: 1
  providers: {}

设 enabled: false 可以完全禁用远程拉取，永远用仓库内快照。

自托管清单

第三方可以用同样 schema 自托管策展清单：

model_catalog:
  providers:
    openrouter:
      url: https://example.com/my-openrouter-curation.json

覆盖清单只需要填关心的 Provider 块，其他 Provider 继续走主 URL。

隐藏 Provider

excluded_providers 可以把某些 Provider 从选择器里藏起来，即使有有效凭据也不显示。适合那些遗留或测试用的凭据还留在 auth.json 里、但日常不想出现的情况：

model_catalog:
  excluded_providers:
    - copilot
    - openrouter
    - openai

这个排除对 /model 选择器的所有界面都生效：网关交互式选择器、TUI 选择器、hermes model CLI 选择器。

自定义别名

经常用的模型可以起短名，然后 /model <别名> 就行。两种等价写法。

完整形式（顶层 model_aliases:）——能控制 Provider + base_url：

# ~/.hermes/config.yaml
model_aliases:
  fav:
    model: claude-sonnet-4.6
    provider: anthropic
  grok:
    model: grok-4
    provider: x-ai

短字符串形式（model.aliases.<name>: provider/model）——从命令行写更方便，但不能带自定义 base_url：

hermes config set model.aliases.fav anthropic/claude-opus-4.6
hermes config set model.aliases.grok x-ai/grok-4

两种写法都进同一个加载器。同名时 model_aliases: 的条目优先于 model.aliases: 的。然后就能 /model fav 或 /model grok。用户别名会覆盖内置短名（sonnet、kimi、opus 等）。

Tip

切换生效时机记住三档：CLI（hermes chat）下次启动生效；网关（Telegram/Discord 等）下次新会话生效，老会话保持原模型，要强制全部刷新就 hermes gateway restart；Dashboard 聊天标签下次新建 PTY 生效，当前打开的用 /model 热切。

这一章讲的是「怎么把模型配上去、切过来」。下一章我们进入更进阶的话题——当单个 Provider 不够用时，怎么用路由规则、Fallback 链和凭据池让多个 Provider 协同工作，实现成本最优和故障自动转移。