hermes教程-配置模型

配置模型

Hermes 使用两种模型插槽：

• 主模型 — 智能体用于思考的模型。每条用户消息、每次工具调用循环、每个流式响应都通过此模型处理。
• 辅助模型 — 智能体卸载的较小副任务。包括上下文压缩、视觉（图像分析）、网页摘要、审批评分、MCP 工具路由、会话标题生成和技能搜索。每个任务都有独立的插槽，可以单独覆盖。

本页介绍如何从仪表盘配置这两种模型。如果你更喜欢配置文件或 CLI，请跳到底部的替代方法。

提示 — 最快路径：Nous Portal

Nous Portal 提供 300 多个模型，只需一个订阅。在新安装时，运行 hermes setup --portal 即可一次性登录并将 Nous 设置为你的提供商。使用 hermes portal info 检查已连接的配置。

• Portal 订阅者还可享受基于令牌计费的提供商 10% 折扣。

注意 — model: 模式：空字符串 vs. 映射

在新安装的默认配置中，model: ""（一个空字符串哨兵，表示“尚未配置”）。当你首次运行 hermes setup 或 hermes model 时，该键会原地升级为包含 provider、default、base_url 和 api_mode 子键的映射——即本页及 profiles.md / configuration.md 中展示的格式。如果你在 config.yaml 中看到空字符串，请运行 hermes model（或点击仪表盘中的 Change），Hermes 会为你写入字典形式。

模型页面

打开仪表盘，点击侧边栏中的 Models。你会看到两个部分：

1. 模型设置 — 顶部面板，用于为插槽分配模型。
2. 使用分析 — 排名卡片，显示在选定时间段内运行过会话的每个模型，包含令牌数、成本和能力徽章。

顶部卡片是模型设置面板。主行始终显示智能体为新会话启动的模型。点击 Change 打开选择器。

设置主模型

点击主模型行上的 Change：

选择器有两列：

• 左侧 — 已认证的提供商。只有你已设置（设置了 API 密钥、OAuth 或定义为自定义端点）的提供商才会显示在这里。如果缺少某个提供商，请前往 Keys 添加其凭据。
• 右侧 — 选定提供商的精选模型列表。这些是 Hermes 为该提供商推荐的智能体模型，而不是原始的 /models 转储（在 OpenRouter 上，后者包含 400 多个模型，包括 TTS、图像生成器和重排序器）。

在过滤框中输入内容，可按提供商名称、别名或模型 ID 进行筛选。

选择一个模型，点击 Switch，Hermes 会将其写入 ~/.hermes/config.yaml 的 model 部分。这仅适用于新会话——任何已打开的聊天标签页将继续使用其启动时的模型。要热切换当前聊天，请在其中使用 /model 斜杠命令。

设置辅助模型

点击 Show auxiliary 展开 11 个任务插槽：

每个辅助任务默认为 auto——意味着 Hermes 也会尝试使用你的主模型来完成该任务。如果该路径不可用或遇到容量类故障，auto 会依次尝试任务特定的 auxiliary.<task>.fallback_chain，然后是主 fallback_providers / fallback_model 链，最后是 Hermes 内置的辅助发现链。当你希望为副任务使用更便宜或更快的模型时，可以覆盖特定任务。

常见覆盖模式

按任务覆盖

点击任何辅助行上的 Change。打开相同的选择器，行为相同——选择提供商 + 模型，点击 Switch。该行会更新显示 provider · model，而不是 auto (use main model)。

全部重置为 auto

如果你过度调整并想重新开始，请点击辅助部分顶部的 Reset all to auto。所有插槽将恢复为使用你的主模型。

“Use as”快捷方式

页面上的每个模型卡片都有一个 Use as 下拉菜单。这是快速路径——在分析中选择一个模型，点击 Use as，然后一键将其分配给主插槽或任何特定的辅助任务：

下拉菜单包含：

• Main model — 与点击主行上的 Change 相同。
• All auxiliary tasks — 将此模型一次性分配给所有 11 个辅助插槽。当你希望所有副任务都使用一个便宜的 flash 模型时非常有用。
• Individual task options — 视觉、网页提取、压缩等。每个任务当前分配的模型会标记为 current。

卡片上会标记 main 或 aux · <task>，表示它们当前已分配给某个任务——这样你可以一目了然地看到哪些历史模型被连接到了哪里。

写入 config.yaml 的内容

当你通过仪表盘保存时，Hermes 会写入 ~/.hermes/config.yaml：

主模型：

model:
  provider: openrouter
  default: anthropic/claude-opus-4.7
  base_url: ''        # 切换提供商时清除
  api_mode: chat_completions

辅助覆盖（示例——视觉使用 gemini-flash）：

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

辅助设为 auto（默认）：

auxiliary:
  compression:
    provider: auto
    model: ''
    base_url: ''
## ... 其他字段不变

provider: auto 且 model: '' 告诉 Hermes 对该任务使用主模型，同时如果主路径无法服务辅助调用，仍会遵循回退策略。

可选的特定任务回退链位于同一辅助任务下：

auxiliary:
  title_generation:
    provider: auto
    model: ''
    fallback_chain:
      - provider: openrouter
        model: inclusionai/ring-2.6-1t:free

当 fallback_chain 不存在时，auto 会在内置辅助发现链之前使用顶层 fallback_providers 链。

何时生效？

• CLI（hermes chat）：下一次 hermes chat 调用。
• 网关（Telegram、Discord、Slack 等）：下一次新会话。现有会话保留其模型。如果你希望强制所有会话获取更改，请重启网关（hermes gateway restart）。
• 仪表盘聊天标签页（/chat）：下一个新 PTY。当前打开的聊天保留其模型——使用其中的 /model 进行热切换。

更改不会使正在运行的会话上的提示缓存失效。这是有意为之：在会话内切换主模型需要重置缓存（系统提示包含特定于模型的内容），我们将其保留给聊天中的显式 /model 斜杠命令。

故障排除

选择器中“没有已认证的提供商”

Hermes 仅在有有效凭据时才会列出提供商。检查侧边栏中的 Keys——你应该看到以下之一：API 密钥、成功的 OAuth 或自定义端点 URL。如果你想要的提供商不在那里，请运行 hermes setup 进行连接，或前往 Keys 添加环境变量。

主模型在正在运行的聊天中没有更改

这是预期的。仪表盘写入 config.yaml，新会话会读取它。当前打开的聊天是一个活动的智能体进程——它保留启动时使用的模型。在聊天中使用 /model <name> 热切换该特定会话。

辅助覆盖“未生效”

检查三件事：

1. 你是否启动了新会话？ 现有聊天不会重新读取配置。
2. provider 是否设置为 auto 以外的值？ 如果字段显示 auto，则该任务仍在使用你的主模型。点击 Change 并选择一个真实的提供商。
3. 提供商是否已认证？ 如果你将 minimax 分配给一个任务但没有 MiniMax API 密钥，该任务会回退到 openrouter 默认值，并在 agent.log 中记录警告。

我选择了一个模型，但 Hermes 切换了我的提供商

在 OpenRouter（或任何聚合器）上，裸模型名称首先在聚合器内部解析。因此，OpenRouter 上的 claude-sonnet-4 会变成 anthropic/claude-sonnet-4.6，保留在你的 OpenRouter 认证上。但如果你在原生 Anthropic 认证上输入了 claude-sonnet-4，它会保持为 claude-sonnet-4-6。如果你看到意外的提供商切换，请检查你当前的提供商是否如你所预期——选择器始终在对话框顶部显示当前主模型。

替代方法

CLI 斜杠命令

在任何 hermes chat 会话中：

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

--global 执行与仪表盘 Change 按钮相同的操作，同时还会原地切换正在运行的会话。

自定义别名

为你经常使用的模型定义自己的短名称，然后在 CLI 或任何消息平台中使用 /model <alias>。有两种等效格式——选择适合你工作流程的一种。

规范格式（顶层 model_aliases:） — 完全控制提供商和 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） — 从 shell 中很方便，因为 hermes config set 只写入标量值，但它无法携带自定义 base_url：

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

两种路径都使用相同的加载器（hermes_cli/model_switch.py）。在 model_aliases: 中声明的条目优先于同名的 model.aliases: 条目。

然后在聊天中使用 /model fav 或 /model grok。用户别名会覆盖内置短名称（sonnet、kimi、opus 等）。请参阅自定义模型别名获取完整参考。

hermes model 子命令

hermes model            # 交互式提供商 + 模型选择器（切换默认值的规范方式）

hermes model 会引导你选择提供商、进行认证（OAuth 流程会打开浏览器；API 密钥提供商会提示输入密钥），然后从该提供商的精选目录中选择特定模型。选择结果会写入 ~/.hermes/config.yaml 的 model.provider 和 model.model。

要列出提供商/模型而不启动选择器，请使用仪表盘或下面的 REST 端点。要检查 CLI 当前实际将使用什么：hermes config show | grep '^model\.' 和 hermes status。

直接编辑配置

编辑 ~/.hermes/config.yaml 并重启读取它的任何内容。请参阅配置参考获取完整模式。

REST API

仪表盘使用三个端点。适用于脚本编写：

## 列出已认证的提供商 + 精选模型列表
curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/options
## 读取当前主模型 + 辅助分配
curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/auxiliary
## 设置主模型
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"main","provider":"openrouter","model":"anthropic/claude-opus-4.7"}' \
  http://localhost:PORT/api/model/set
## 覆盖单个辅助任务
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"vision","provider":"openrouter","model":"google/gemini-2.5-flash"}' \
  http://localhost:PORT/api/model/set
## 将一个模型分配给所有辅助任务
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"","provider":"openrouter","model":"google/gemini-2.5-flash"}' \
  http://localhost:PORT/api/model/set
## 将所有辅助任务重置为 auto
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"__reset__","provider":"","model":""}' \
  http://localhost:PORT/api/model/set

会话令牌在启动时注入到仪表盘 HTML 中，并在每次服务器重启时轮换。如果你要针对正在运行的仪表盘编写脚本，请从浏览器开发者工具（window.__HERMES_SESSION_TOKEN__）中获取它。