Hermes Agent 配置模型完全教程：交互式 / config.yaml / 多模型切换 / 401 排障（2026）

📚 本文是 AI 工具完全指南（2026）：ChatGPT、Gemini、Kimi 与生产力工具怎么选怎么用 的配套教程。想系统了解 AI 工具怎么选、国内怎么访问、按场景怎么用，欢迎访问总览页。

Hermes Agent 配置模型完全教程（2026）

Hermes Agent 的模型配置有两种方式：交互式向导（hermes model）和手动编辑 config.yaml。本文基于 Hermes Agent v0.19.x（Windows 原生安装）实际配置经验，覆盖两种配置方式、8 家常见提供商的配置方法、自定义 Provider 接入任意 OpenAI 兼容端点、多模型别名切换、辅助模型配置，以及一个很容易踩坑的 host 安全门控机制（”配了 key 却报 401”）。

目录

• 一、配置方式总览
• 二、方式一：交互式配置（hermes model）
• 三、方式二：编辑配置文件（推荐、可复现）
  • 3.1 配置文件在哪里
  • 3.2 一等提供商（官方集成）
  • 3.3 命名 Custom Provider（任意 OpenAI 兼容端点）
  • 3.4 多模型配置与切换
  • 3.5 辅助模型配置
• 四、验证配置是否生效
• 五、常见坑：为什么我配了 key 却报 401？
• 六、完整示例：三模型共存配置
• 七、FAQ

---

一、配置方式总览

Hermes 的模型配置存储在两个文件里：

文件	作用	存放内容
config.yaml	模型、provider、终端等非敏感配置	provider、base_url、默认模型、别名
.env	敏感信息	API Key 等环境变量

Windows 路径：%LOCALAPPDATA%\hermes\（即 C:\Users\<用户名>\AppData\Local\hermes\）
Linux / macOS 路径：~/.hermes/

配置优先级（从高到低）：

1. CLI 参数（如 hermes chat --model xxx）
2. config.yaml
3. .env
4. 内置默认值

两种配置方式任选其一：

• 交互式：运行 hermes model 或 hermes setup，跟着向导选择
• 手动：直接编辑 config.yaml + .env（适合多模型、团队复现、快速切换）

---

二、方式一：交互式配置（hermes model）

hermes model

进入交互界面后：

1. 选择提供商（OpenRouter、DeepSeek、Anthropic、自定义端点等）
2. 按提示输入 API Key
3. 选择具体模型
4. 确认后即写入配置

常用配套命令：

hermes setup          # 完整配置向导（模型、终端、消息平台等）
hermes config set model.provider deepseek    # 命令行直接设置
hermes config set model.default deepseek-chat
hermes config set OPENROUTER_API_KEY sk-or-xxx   # key 会自动写入 .env

交互式方式适合第一次配置、只有一个模型的情况；多模型管理建议用手动方式。

---

三、方式二：编辑配置文件（推荐、可复现）

3.1 配置文件在哪里

hermes config edit    # 直接用编辑器打开 config.yaml

编辑后无需重启，下一次 hermes chat 自动生效（与 opencode 不同，Hermes 每次运行都会重新读取配置）。但已打开的会话不会热更新，需要开新会话或在会话内用 /model 切换。

3.2 一等提供商（官方集成）

Hermes 对常见厂商有内置集成，只需在 .env 设置对应变量，provider 填内置名字：

提供商	.env 变量	provider 值	默认端点
OpenRouter	OPENROUTER_API_KEY	openrouter	openrouter.ai
DeepSeek 官方	DEEPSEEK_API_KEY	deepseek	api.deepseek.com
z.ai / GLM	GLM_API_KEY	zai	api.z.ai
Kimi	KIMI_API_KEY	kimi-coding	api.kimi.com
MiniMax	MINIMAX_API_KEY	minimax	api.minimax.io
Google Gemini	GOOGLE_API_KEY	gemini	AI Studio
Hugging Face	HF_TOKEN	huggingface	router.huggingface.co
阿里云 Qwen	DASHSCOPE_API_KEY	alibaba	DashScope

示例（.env）：

DEEPSEEK_API_KEY=sk-你的DeepSeek密钥

示例（config.yaml）：

model:
  default: deepseek-chat
  provider: deepseek

3.3 命名 Custom Provider（任意 OpenAI 兼容端点）

公司内部网关、私有化部署、国内镜像端点等，往往不是官方端点。这时要在 config.yaml 的 providers: 段定义一个命名 provider：

providers:
  my-vendor:                    # 自定义名字，全局唯一
    name: 我的模型服务           # 显示名（可选）
    base_url: https://api.example.com/v1
    key_env: MY_VENDOR_API_KEY   # 指定 key 从哪个环境变量读取
    default_model: my-model-x    # 该端点的默认模型 ID
    api_mode: chat_completions   # OpenAI 兼容协议

.env 中对应设置：

MY_VENDOR_API_KEY=sk-你的密钥

然后让默认模型指向它：

model:
  default: my-model-x
  provider: my-vendor
  base_url: https://api.example.com/v1

为什么要用 key_env？因为 Hermes 有 host 安全门控机制（见第五节）。用 key_env 明确指定变量名，是给任意自定义端点配 key 的唯一可靠方式。

3.4 多模型配置与切换

多个 provider 可以共存，互不影响：

model:
  default: glm-5.2
  provider: talkweb-glm
  aliases:
    glm-5.2: talkweb-glm/glm-5.2
    deepseek-v4-flash: talkweb-deepseek-flash/deepseek-v4-flash
    inner-deepseek: inner-deepseek/DeepSeek-R1
providers:
  talkweb-glm: { ... }
  talkweb-deepseek-flash: { ... }
  inner-deepseek: { ... }

aliases 给每个模型定义好记的短名字。会话中切换：

/model glm-5.2
/model deepseek-v4-flash

命令行单次指定：

hermes chat --model glm-5.2
hermes chat -m inner-deepseek

3.5 辅助模型配置

Hermes 除了主模型（Main model）外，还支持辅助模型（Auxiliary models），用于上下文压缩、视觉分析、网页摘要、审批评分、MCP 工具路由、会话标题生成等边缘任务。每个任务有独立槽位，可以单独覆盖。

默认所有辅助任务都是 auto，即跟随主模型。当主模型不支持某能力或想省钱时，可以给特定任务指定更便宜的模型：

auxiliary:
  vision:
    provider: openrouter
    model: google/gemini-2.5-flash  # 主模型不支持视觉时，用 gemini flash
  compression:
    provider: deepseek
    model: deepseek-chat  # 上下文压缩用便宜模型，省推理 token
  title_gen:
    provider: openrouter
    model: google/gemini-3-flash-preview  # 标题生成用最便宜的 flash

常见覆盖场景：

辅助任务	何时覆盖	推荐模型
标题生成	几乎总是——$0.10/M 的 flash 写标题和 Opus 一样好	gemini-flash / gpt-5-mini
视觉	主模型不支持图片时	gemini-2.5-flash / gpt-4o-mini
上下文压缩	用 Opus/M2.7 的推理 token 摘要太浪费	deepseek-chat / 任意便宜 chat 模型
审批评分	approval_mode: smart 时	haiku / flash / gpt-5-mini

---

四、验证配置是否生效

hermes config                 # 查看当前解析出的配置
hermes doctor                 # 体检：检查 key、依赖、配置版本
hermes doctor --fix           # 自动修复可修复项（如配置版本迁移）

非交互式快速实测（脚本里验证非常好用）：

hermes chat -q "你好，用一句话介绍你自己" -Q

• -q：单条消息模式，不会进入交互界面
• -Q：安静模式，只输出最终回复（可用于 CI / 脚本）

若输出正常回复，说明模型链路完全打通。

---

五、常见坑：为什么我配了 key 却报 401？

症状：hermes chat 报 HTTP 401: Invalid token，但用 curl / Python 直接调同一个端点却完全正常。

原因在 Hermes 的 host 安全门控。出于防止 API Key 被泄露给无关服务器的考虑，Hermes 对 API Key 的使用有严格限制：

1. OPENAI_API_KEY 只会发给 openai.com / openai.azure.com 的主机；
2. OPENROUTER_API_KEY 只会发给 openrouter.ai；
3. 其他主机名会尝试推导 <VENDOR>_API_KEY（如 api.deepseek.com → DEEPSEEK_API_KEY）；
4. IP 地址、localhost 无法推导 vendor 名，于是 key 解析结果为空；
5. key 为空时，自定义端点会退化为占位符 no-key-required 发送出去，网关拒绝，返回 401。

解决办法：不要用 OPENAI_API_KEY 给自定义端点配 key，改用命名 custom provider + key_env：

providers:
  inner-deepseek:
    base_url: http://10.0.59.210:8080/v2   # IP 地址也完全没问题
    key_env: INNER_DEEPSEEK_API_KEY          # 关键：显式指定变量名
    default_model: DeepSeek-R1
    api_mode: chat_completions

# .env
INNER_DEEPSEEK_API_KEY=sk-真正的密钥

其他常见问题：

• hermes 命令找不到：安装后 PATH 生效需要重开 PowerShell。
• 配置版本过旧：hermes doctor --fix 自动迁移。
• 交互式 TUI 报 NoConsoleScreenBufferError：hermes chat 需要真实控制台，脚本里请用 -q。
• 改完没生效：检查是否改了正确的文件（Windows 是 %LOCALAPPDATA%\hermes\，不是 ~/.hermes/），运行 hermes config 确认解析结果。

---

六、完整示例：三模型共存配置

一个生产可用的完整配置（一内网端点 + 一云端网关两个模型）：

config.yaml：

model:
  default: deepseek-v4-flash
  provider: talkweb-deepseek-flash
  base_url: https://hlyc.talkweb.com.cn/v1
  aliases:
    glm-5.2: talkweb-glm/glm-5.2
    deepseek-v4-flash: talkweb-deepseek-flash/deepseek-v4-flash
    inner-deepseek: inner-deepseek/DeepSeek-R1

auxiliary:
  title_gen:
    provider: talkweb-deepseek-flash
    model: deepseek-v4-flash
  compression:
    provider: talkweb-deepseek-flash
    model: deepseek-v4-flash

providers:
  inner-deepseek:
    name: 内网 DeepSeek-R1
    base_url: http://10.0.59.210:8080/v2
    key_env: INNER_DEEPSEEK_API_KEY
    default_model: DeepSeek-R1
    api_mode: chat_completions

  talkweb-glm:
    name: 拓维 GLM-5.2
    base_url: https://hlyc.talkweb.com.cn/v1
    key_env: TALKWEB_GLM_API_KEY
    default_model: glm-5.2
    api_mode: chat_completions

  talkweb-deepseek-flash:
    name: 拓维 DeepSeek V4 Flash
    base_url: https://hlyc.talkweb.com.cn/v1
    key_env: TALKWEB_GLM_API_KEY
    default_model: deepseek-v4-flash
    api_mode: chat_completions

.env：

INNER_DEEPSEEK_API_KEY=sk-内网密钥
TALKWEB_GLM_API_KEY=sk-拓维密钥

验证：

hermes chat -q "你好" -Q                    # 默认模型
hermes chat -q "你好" -Q --model glm-5.2    # 指定模型
hermes doctor                               # 体检

---

七、FAQ

Hermes Agent 和 OpenClaw / Claude Code 有什么区别？

Hermes Agent 是开源 AI 智能体框架，支持多模型提供商、终端工具、消息平台接入（飞书/微信/Discord）、技能系统和 MCP 集成。和 OpenClaw 类似但社区更活跃，对 Windows 原生安装适配也更好。

Hermes Agent 支持哪些消息平台？

通过 gateway 接入飞书、微信、QQ、Discord、WhatsApp、Signal、邮件、Home Assistant 等。运行 hermes gateway setup 配置。

配置文件改了但不生效？

确认改对了文件（Windows 是 %LOCALAPPDATA%\hermes\），运行 hermes config 看解析结果。已打开的会话不会热更新，需要开新会话或用 /model 切换。

能同时用多个模型的 API Key 吗？

能。每个 provider 用独立的 key_env 指定不同的环境变量，互不影响。.env 文件里可以放多个 key。

---

参考链接

• 官方文档（中文社区）：https://hermesagent.org.cn
• 环境变量参考：https://hermesagent.org.cn/docs/reference/environment-variables
• 模型配置：https://hermesagent.org.cn/docs/user-guide/configuring-models
• AI 提供商：https://hermesagent.org.cn/docs/integrations/providers

想了解更多 AI 工具的选型和用法？回到 AI 工具完全指南（2026） 看总览。