【AI 工具】Hermes Agent 模型配置指南

核心概念

Hermes 的模型配置分为三层：

主模型层：对话主力军，负责核心推理
辅助模型层：轻量级任务专用（图像识别、网页总结、上下文压缩）
回退链层：主模型挂了自动切换备胎

配置文件位置：~/.hermes/config.yaml

环境变量替换

在 config.yaml 中可以使用 ${VAR_NAME} 语法引用环境变量，避免硬编码敏感信息：

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

特性：

单个值中可以有多个引用：url: "${HOST}:${PORT}"
如果引用的变量未设置，占位符保持原样（${UNDEFINED_VAR} 不变）
仅支持 ${VAR} 语法 —— 裸 $VAR 不会被展开

环境变量来源：

系统环境变量
~/.hermes/.env 文件中定义的变量（推荐）

模型配置字段详解

Hermes 的模型配置由三个核心字段组成：

`model` — 主模型配置

定义默认对话模型及其连接方式：

default：默认模型名称（如 anthropic/claude-opus-4.6）
provider：推理提供商（内置值如 openrouter、anthropic，**自定义端点时只能写 custom**，不能写 custom_providers 里的名字）
base_url：API 端点（自定义端点时必填）
api_key：API 密钥
api_mode：API 模式（chat_completions | anthropic_messages 等）
context_length：上下文长度（留空自动检测）
supports_vision：是否原生支持视觉

⚠️ 官方规定： 使用自定义端点时，model.provider 必须是 custom。写入 model.provider: uih-cri 等 custom_providers 的命名是无效的，provider 字段只接受内置 provider ID。参考官方文档：AI Providers。

`fallback_providers` — 回退链配置

主模型遇到限流、服务器错误、认证失败时自动按顺序切换。

provider 的合法值同样是内置 provider（如 openrouter、nous、anthropic）或 custom
model：回退时使用的模型名
base_url、api_key、key_env：自定义端点专属字段

⚠️ 官方规定： fallback_providers[].provider 也不能写 custom_providers 里的名字，必须使用 custom 并配合 base_url。官方参考：Fallback Providers。

`custom_providers` — 自定义提供商命名

管理多个自定义端点（本地模型、公司内网、第三方服务）。

name：给端点起的别名，仅用于 /model 命令快速切换（如 /model custom:uih-cri:gpt-5.5）或 Dashboard 模型选择器
base_url、key_env、api_mode：端点的连接信息

💡 name ≠ provider 值。 命名在 model.provider 和 fallback_providers[].provider 里是不能用的。它只能通过 /model 或 Dashboard 模型选择器被引用。官方参考：Named Custom Providers。

🤔 那我定义 custom_providers 到底有啥用？ 简单说：你只有一个自定义端点，不写 custom_providers 也完全 OK，直接用 model.provider: custom + model.base_url 就行。custom_providers 的存在意义是你有多个自定义端点，不想每次手动改 base_url，用 /model custom:名字:模型 就能一键切换。比如你在公司用 uih-cri，在家用 local-qwen，只用一条斜杠命令就能来回切，这才是它的真正价值。

实战配置方案

三种场景，一个共用的 .env 文件，三个不同的 config.yaml。

共用的 `.env` 文件

**~/.hermes/.env**（所有场景共用）：

# 场景一：UIH 内网
UIH_CRI_URL="http://10.8.190.12:3310/openai/v1"
UIH_CRI_KEY="PEJe...Hx0"
UIHAI_URL="https://ai-infra.united-imaging.com/v1/"
UIHAI_KEY="sk-2hT...LI3S"

# 场景二：IMIT 内网
LOCAL_QWEN_URL="http://172.21.8.197:6080/v1"
LOCAL_QWEN_KEY="123456"
LOCAL_GLM_URL="http://172.21.8.196:6080/v1"
LOCAL_GLM_KEY="123456"
LOCAL_KIMI_URL="http://172.21.8.195:6080/v1"
LOCAL_KIMI_KEY="123456"

# 场景三：家里（白嫖 ModelScope）
MODELSCOPE_URL="https://api-inference.modelscope.cn/v1/"
MODELSCOPE_KEY="ms-4058...e5"

方案一：UIH 内网（公司）

场景：在公司，使用内网 API 服务。

配置策略：

主模型：uih-cri 的 gpt-5.5
回退链：uihai 的 glm-5.1 → MiniMax-M2.7 → Kimi-K2.5

config.yaml 配置：

# 主模型：uih-cri 的 gpt-5.5
model:
  default: "gpt-5.5"
  provider: "custom"
  base_url: ${UIH_CRI_URL}
  api_key: ${UIH_CRI_KEY}

# 回退链：uihai 的 glm-5.1 → MiniMax-M2.7 → Kimi-K2.5
fallback_providers:
  - provider: custom
    model: "glm-5.1"
    base_url: ${UIHAI_URL}
    api_key: ${UIHAI_KEY}
  - provider: custom
    model: "MiniMax-M2.7"
    base_url: ${UIHAI_URL}
    api_key: ${UIHAI_KEY}
  - provider: custom
    model: "Kimi-K2.5"
    base_url: ${UIHAI_URL}
    api_key: ${UIHAI_KEY}

# 自定义提供商命名（方便 /model 切换）
custom_providers:
  - name: uih-cri
    base_url: ${UIH_CRI_URL}
    key_env: UIH_CRI_KEY
  
  - name: uihai
    base_url: ${UIHAI_URL}
    key_env: UIHAI_KEY

# 辅助任务：用 uihai 的模型（省钱）
auxiliary:
  vision:
    provider: "custom"
    model: "glm-5.1"
    base_url: ${UIHAI_URL}
    api_key: ${UIHAI_KEY}
  compression:
    provider: "custom"
    model: "glm-5.1"
    base_url: ${UIHAI_URL}
    api_key: ${UIHAI_KEY}

方案二：IMIT 内网

场景：在IMIT使用内网本地模型服务。

配置策略：

主模型：local-qwen 的 Qwen3.5-397B-A17B
回退链：local-kimi 的 Kimi-K2.6 → local-glm 的 GLM-5.1

config.yaml 配置：

# 主模型：local-qwen 的 Qwen3.5-397B-A17B
model:
  default: "Qwen3.5-397B-A17B"
  provider: "custom"
  base_url: ${LOCAL_QWEN_URL}
  api_key: ${LOCAL_QWEN_KEY}

# 回退链：local-kimi → local-glm
fallback_providers:
  - provider: custom
    model: "Kimi-K2.6"
    base_url: ${LOCAL_KIMI_URL}
    api_key: ${LOCAL_KIMI_KEY}
  - provider: custom
    model: "GLM-5.1"
    base_url: ${LOCAL_GLM_URL}
    api_key: ${LOCAL_GLM_KEY}

# 自定义提供商命名（方便 /model 切换）
custom_providers:
  - name: local-qwen
    base_url: ${LOCAL_QWEN_URL}
    key_env: LOCAL_QWEN_KEY
  
  - name: local-kimi
    base_url: ${LOCAL_KIMI_URL}
    key_env: LOCAL_KIMI_KEY
  
  - name: local-glm
    base_url: ${LOCAL_GLM_URL}
    key_env: LOCAL_GLM_KEY

方案三：家里（白嫖 ModelScope）

场景：在家，使用 ModelScope 免费额度。

配置策略：

主模型：ModelScope 的 Qwen/Qwen3.5-397B-A17B
回退链：ModelScope 的 ZhipuAI/GLM-5.1 → MiniMax/MiniMax-M2.7 → moonshotai/Kimi-K2.6

config.yaml 配置：

# 主模型：ModelScope 的 Qwen3.5
model:
  default: "Qwen/Qwen3.5-397B-A17B"
  provider: "custom"
  base_url: ${MODELSCOPE_URL}
  api_key: ${MODELSCOPE_KEY}

# 回退链：GLM → MiniMax → Kimi
fallback_providers:
  - provider: custom
    model: "ZhipuAI/GLM-5.1"
    base_url: ${MODELSCOPE_URL}
    api_key: ${MODELSCOPE_KEY}
  - provider: custom
    model: "MiniMax/MiniMax-M2.7"
    base_url: ${MODELSCOPE_URL}
    api_key: ${MODELSCOPE_KEY}
  - provider: custom
    model: "moonshotai/Kimi-K2.6"
    base_url: ${MODELSCOPE_URL}
    api_key: ${MODELSCOPE_KEY}

# 自定义提供商命名
custom_providers:
  - name: modelscope
    base_url: ${MODELSCOPE_URL}
    key_env: MODELSCOPE_KEY

辅助模型配置（auxiliary）

Hermes 用独立轻量模型处理特定任务，避免浪费主模型的昂贵 token。

11 个辅助任务

|| 任务 | 用途 | 配置键 |
|:—|:—|:—|
|| vision | 图像分析、浏览器截图 | auxiliary.vision |
|| web_extract | 网页抓取/总结 | auxiliary.web_extract |
|| compression | 上下文压缩 | auxiliary.compression |
|| skills_hub | 技能搜索 | auxiliary.skills_hub |
|| mcp | MCP 工具路由 | auxiliary.mcp |
|| approval | 命令审批判断 | auxiliary.approval |
|| title_generation | 会话标题生成 | auxiliary.title_generation |
|| triage_specifier | 看板任务细化（把一句话转成详细 spec） | auxiliary.triage_specifier |
|| kanban_decomposer | 看板任务拆解（拆分任务图为子任务） | auxiliary.kanban_decomposer |
|| profile_describer | Profile 描述自动生成 | auxiliary.profile_describer |
|| curator | 技能使用审查 | auxiliary.curator |

配置示例

auxiliary:
  # 视觉任务：用便宜的 Gemini Flash
  vision:
    provider: "openrouter"
    model: "google/gemini-2.5-flash"
    timeout: 30
  
  # 上下文压缩：用最便宜的模型
  compression:
    provider: "auto"
    model: "google/gemini-3-flash-preview"
  
  # 网页总结：和视觉共用一个模型
  web_extract:
    provider: "auto"
    model: ""

provider 可选值

值	含义
`"auto"`	自动检测（默认）
`"openrouter"`	强制 OpenRouter
`"nous"`	强制 Nous Portal
`"codex"`	强制 Codex OAuth
`"main"`	和主模型用同一个
`"anthropic"`	强制 Anthropic 原生

不设 auxiliary 会默认用主模型

如果不配置 auxiliary 部分，或者保持默认的空配置（provider: "auto" + model: ""），Hermes 会自动将所有辅助任务路由到你的主模型

参考

model: https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models
auxiliary: https://hermes-agent.nousresearch.com/docs/user-guide/configuration#auxiliary-models
fallback_providers: https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers
custom_providers: https://hermes-agent.nousresearch.com/docs/integrations/providers

核心概念

环境变量替换

模型配置字段详解

model — 主模型配置

fallback_providers — 回退链配置

custom_providers — 自定义提供商命名

实战配置方案

共用的 .env 文件

方案一：UIH 内网（公司）

方案二：IMIT 内网

方案三：家里（白嫖 ModelScope）

辅助模型配置（auxiliary）

11 个辅助任务

配置示例

provider 可选值

不设 auxiliary 会默认用主模型

参考

`model` — 主模型配置

`fallback_providers` — 回退链配置

`custom_providers` — 自定义提供商命名

共用的 `.env` 文件