Skip to main content

配置模型

Hermes 使用两种类型的模型槽位：

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

本页介绍如何通过仪表板配置这两类模型。若更倾向于使用配置文件或 CLI，请参阅文末的 其他方法。

模型页面​

打开仪表板后，在侧边栏点击 模型。页面分为两个部分：

  1. 模型设置 — 顶部面板，用于为各个槽位分配模型。
  2. 使用情况分析 — 排名卡片展示在选定时间段内运行过的所有模型，包含 token 数量、成本以及功能标签。

模型页面概览

最上方的卡片是 模型设置 面板。主行始终显示新会话将启动的模型。点击 更改 可打开选择器。

设置主模型​

点击主模型行的 更改：

模型选择弹窗

选择器包含两列：

  • 左侧 — 已认证的服务提供商。仅列出您已配置（设置 API 密钥、完成 OAuth 授权或定义自定义端点）的提供商。若缺少所需提供商，请前往 密钥 页面添加凭证。
  • 右侧 — 所选提供商的精选模型列表。这些是 Hermes 推荐用于该提供商的智能体专用模型，并非原始 /models 列表（例如 OpenRouter 包含 400+ 模型，涵盖 TTS、图像生成器和重排序模型等）。

在过滤框中输入关键词，可按提供商名称、缩写或模型 ID 进行筛选。

选择一个模型，点击 切换，Hermes 会将其写入 ~/.hermes/config.yaml 中的 model 部分。此设置仅适用于新会话 —— 已打开的聊天标签将继续运行其初始模型。如需热替换当前聊天的模型，可在其中使用 /model 命令。

设置辅助模型​

点击 显示辅助 以展开八个任务槽位：

展开的辅助面板

每个辅助任务默认使用 auto —— 即 Hermes 会使用您的主模型来执行该任务。当您希望为某个子任务使用更便宜或更快的模型时，可进行单独覆盖。

常见覆盖场景​

任务何时应覆盖
标题生成几乎总是。$0.10/M 的快速模型与 Opus 一样能写出优质会话标题。默认配置在 OpenRouter 上将此任务设为 google/gemini-3-flash-preview。
视觉分析当主模型是无视觉能力的代码模型时（如 Kimi、DeepSeek）。可指向 google/gemini-2.5-flash 或 gpt-4o-mini。
上下文压缩当您在 Opus/M2.7 上耗费推理 token 来压缩上下文时。一个快速聊天模型可实现相同效果，成本仅为 1/50。
审批决策对于 approval_mode: smart —— 使用快速/廉价模型（如 haiku、flash、gpt-5-mini）判断是否自动批准低风险指令。在此处使用昂贵模型属于浪费。
网页提取当您频繁使用 web_extract 时。逻辑同压缩：摘要无需复杂推理。
技能中心hermes skills search 使用此功能。通常在 auto 下表现良好即可。
MCP 路由MCP 工具路由。通常在 auto 下表现良好即可。

逐任务覆盖​

点击任意辅助行的 更改。弹出相同的选择器，行为一致：选择提供商 + 模型，点击 切换。该行将更新为显示 provider · model，而非 auto (use main model)。

一键重置所有为自动​

若您过度调整配置，想重新开始，可点击辅助区域顶部的 全部重置为自动。所有槽位将恢复为使用主模型。

“使用为” 快捷方式​

页面上每个模型卡片都带有一个 使用为 下拉菜单。这是快速路径：选择您在分析中看到的某个模型，点击 使用为，即可一键将其分配为主模型或任一特定辅助任务：

使用为下拉菜单

下拉菜单包含：

  • 主模型 — 与点击主行的 更改 按钮效果相同。
  • 所有辅助任务 — 将该模型一次性分配给全部 8 个辅助槽位。适合您希望所有子任务都使用廉价快速模型的情况。
  • 单个任务选项 — 如视觉分析、网页提取、压缩等。每个任务当前分配的模型会标记为 current。

卡片会带有 main 或 aux · <task> 标签，表示该模型当前已被分配至某处——因此您可以一目了然地看出哪些历史模型正在被使用。

写入到 config.yaml 的内容​

通过仪表板保存后，Hermes 会写入以下内容：

主模型：

model:
  provider: openrouter
  default: anthropic/claude-opus-4.7
  base_url: ''        # cleared on provider switch
  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

辅助模型自动（默认）：

auxiliary:
  compression:
    provider: auto
    model: ''
    base_url: ''
    # ... other fields unchanged

provider: auto 且 model: '' 表示 Hermes 将使用主模型执行该任务。

何时生效？​

  • CLI（hermes chat）：下次 hermes chat 调用时。
  • 网关（Telegram、Discord、Slack 等）：下次 新 会话。现有会话保持原模型不变。如需强制所有会话应用变更，请重启网关（hermes gateway restart）。
  • 仪表板聊天标签（/chat）：下次新建 PTY 时。当前打开的聊天仍保留原模型 —— 可在其中使用 /model 命令进行热替换。

更改不会使正在运行会话的提示缓存失效。这是有意为之：在会话中更换主模型需要重置缓存（系统提示中包含模型特定内容），我们仅在聊天内明确使用 /model 命令时才执行此操作。

故障排查​

“选择器中无已认证提供商”​

Hermes 仅列出拥有有效凭证的提供商。请检查侧边栏中的 密钥 —— 您应能看到：API 密钥、成功授权的 OAuth，或自定义端点 URL。若目标提供商未出现，请运行 hermes setup 配置，或前往 密钥 添加环境变量。

运行中的聊天中主模型未改变​

属正常现象。仪表板写入的是 config.yaml，新会话读取该值。当前打开的聊天是一个活跃的代理进程，会继续使用其启动时的模型。请使用 /model <name> 在聊天内部进行热替换。

辅助模型覆盖“未生效”​

请检查以下三点：

  1. 是否开启了新会话？ 已存在的聊天不会重新读取配置。
  2. 是否 provider 不等于 auto？ 若字段显示 auto，说明任务仍在使用主模型。请点击 更改 并选择真实提供商。
  3. 提供商是否已认证？ 若为任务分配了 minimax 但未配置 MiniMax API 密钥，则该任务将回退至 openrouter 默认值，并在 agent.log 中记录警告。

我选择了模型，但 Hermes 自动切换了提供商​

在 OpenRouter（或其他聚合平台）上，仅凭模型名称会优先在聚合平台内解析。因此，claude-sonnet-4 在 OpenRouter 上会解析为 anthropic/claude-sonnet-4.6，仍使用您的 OpenRouter 认证。但如果您在原生 Anthropic 认证下输入 claude-sonnet-4，它将保持为 claude-sonnet-4-6。若发现意外的提供商切换，请确认当前使用的提供商是否符合预期 —— 选择器始终在对话顶部显示当前主模型。

其他方法​

CLI 斜杠命令​

在任意 hermes chat 会话中：

/model gpt-5.4 --provider openrouter             # session-only
/model gpt-5.4 --provider openrouter --global    # also persists to config.yaml

--global 的作用与仪表板的 更改 按钮相同，同时还可在当前会话中直接切换模型。

自定义别名​

为经常使用的模型定义自己的短名称，然后在 CLI 或任意消息平台中使用 /model <alias>：

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

或从 shell 中（简写形式，provider/model）：```bash hermes config set model.aliases.fav anthropic/claude-opus-4.6 hermes config set model.aliases.grok x-ai/grok-4


然后在聊天中使用 `/model fav` 或 `/model grok`。用户自定义的别名会覆盖内置的简短名称（如 `sonnet`、`kimi`、`opus` 等）。详见 [自定义模型别名](/docs/reference/slash-commands#custom-model-aliases) 获取完整参考。

### `hermes model` 子命令

```bash
hermes model            # Interactive provider + model picker (the canonical way to switch defaults)

hermes model 会引导您选择一个服务提供商，进行身份验证（OAuth 流程将打开浏览器；API 密钥类提供商则会提示输入密钥），然后从该提供商的精选模型目录中选择一个具体模型。选定的配置将写入 model.provider 和 model.model 中的 ~/.hermes/config.yaml。

若要列出所有可用的服务商和模型但不启动选择器，请使用仪表板或下方的 REST API 端点。若要检查 CLI 当前实际使用的配置：使用 hermes config get model 和 hermes status。

直接编辑配置文件​

直接编辑 ~/.hermes/config.yaml 文件并重启读取该文件的程序。详情参见 配置参考 以获取完整配置结构。

REST API​

仪表板使用三个端点。适用于脚本自动化：

# List authenticated providers + curated model lists
curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/options

# Read current main + auxiliary assignments
curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/auxiliary

# Set the main model
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

# Override a single auxiliary task
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

# Assign one model to every auxiliary task
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

# Reset all auxiliary tasks to 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__）。