Feng's Blog

8.13 Hermes 网关免费模型自动切换与报错修复

Properties1
tagsai工程

8分钟阅读

对话笔记直发：8.13 Hermes 网关免费模型自动切换与报错修复。分类：AI工程。

title: Hermes 网关免费模型自动切换与报错修复 date: 2026-08-13 tags:

  • Hermes
  • Nous
  • Telegram
  • 网关部署
  • sing-box
  • 免费模型
  • 自动切换
  • 云服务器
  • yun1
  • tencent summary: 在 yun1 与 tencent 两台云服务器部署 Hermes Agent 网关（Nous 免费账号 + Telegram + sing-box 代理），修复「model provider failed after retries」404 报错（根因：配置放错路径导致网关回退到付费默认模型），并补齐 jp 已有的免费模型自动切换（model_catalog + fallback_model）。

Hermes 网关免费模型自动切换与报错修复（2026-08-13）

一、部署目标与约束

  • 在 yun1（121.41.*.*，admin）与 tencent（124.222.*.*，root）两台云服务器部署 Hermes Agent 网关。
  • 绑定 Nous 官方免费账号，使用免费 API token 模型；两个独立免费额度账号（不是同一账号）。
  • 配置 Telegram（bot token 来自 @telegram BOT.txt）：hermes1=yun1，hermes2=tencent。
  • egress 走 sing-box 代理 127.0.0.1:7890（参考本地 NAS jp 192.168.*.* 的配置同步）。
  • 硬约束（不可违反）：不得影响 tencent 既有容器服务（omniroute/codex-box 等）；不得影响 yun1 的 ai-chat 前后端容器。

二、最终落地配置（两台一致）

/opt/data/config.yaml（注意路径，见坑 3），属主 hermes:hermes，权限 600：

model: tencent/hy3:free
model_catalog:
  enabled: true
  url: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
  ttl_hours: 1
  providers: {}
fallback_model:
  provider: nous
  model: stepfun/step-3.7-flash:free
  • 服务：hermes-gateway.service（User=hermes，HERMES_HOME=/opt/data，WorkingDirectory=/opt/data，EnvironmentFile=/opt/data/.env）。
  • /opt/data/.env（600，hermes）：含 HTTP_PROXY/HTTPS_PROXY=http://127.0.0.1:7890、NO_PROXY=localhost,127.0.0.1,::1、TELEGRAM_BOT_TOKEN=xxxx、TELEGRAM_ALLOWED_USERS=5359999791。

三、踩过的坑（关键经验）

坑 1：Nous 登录非交互时自动导入共享凭证

  • hermes auth add nous --type oauth --no-browser 检测到 <HERMES_HOME>/shared/nous_auth.json 存在时，在管道/非 TTY 输入下 input() 抛 EOFError 被当作 “y”，自动 rehydrate 共享凭证 → 绑定成错误账号。
  • 修复：删 /opt/data/shared/nous_auth.json（及 .lock）后再跑，才会走 device-code 流程打印新 user_code 链接。
  • 最终两个账号独立：yun1 org_id=nas_organisation:246f1c47-…、tencent org_id=nas_organisation:bda55a46-…（均不同于最初误导入的 cmopzccfr…）。

坑 2：免费模型名写错

  • 误写 tencent/hy3-preview:free → Nous 推理 404「Model not found」。
  • 正确：tencent/hy3:free（直连 https://inference-api.nousresearch.com/v1/chat/completions 返回 200 “PONG”，不计费）。Nous 可用模型共 363 个；tencent/hy3-preview:free 不存在，stepfun/step-3.7-flash:free 存在。

坑 3（本次主因）：配置放错路径 → 网关回退付费默认模型

  • 现象：用户通过 Telegram 发消息，bot 回复 ⚠️ The model provider failed after retries；日志真实报错： 404 Model 'deepseek/deepseek-v4-flash' requires available credits … pick a free model. —— 网关在用付费模型，免费账号无额度。
  • 根因：网关 _load_gateway_config() 读取 _hermes_home / 'config.yaml'（即 /opt/data/config.yaml，源码 gateway/run.py 约 1530 行）；而之前把配置建在了 /opt/data/.hermes/config.yaml（那是 CLI load_config() 的路径）。网关读不到 → 回退内置默认 deepseek/deepseek-v4-flash（付费）→ 404。
  • 修复：把配置写到正确路径 /opt/data/config.yaml，删除误放的 /opt/data/.hermes/config.yaml，重启 hermes-gateway.service。
  • 佐证：jp 的配置文件就在 /opt/data/config.yaml（无 .hermes 那份），与网关加载路径一致。

四、jp 的「免费模型自动切换」机制（已复刻到云上）

  • model_catalog：Hermes 每小时拉取 Nous 的当前免费/推荐模型清单（/api/nous/recommended-models 的 freeRecommendedModels 是「当前免费模型」真相源），供模型选择器感知最新免费款。目录 URL 实际 301 重定向到 nousresearch.github.io/.../model-catalog.json，经代理返回 200 有效 JSON。
  • fallback_model：主模型调用失败时自动回退到另一个 :free 模型（stepfun/step-3.7-flash:free）。
  • 局限（与 jp 一致）：网关主模型是静态值。当 tencent/hy3:free 不再免费时，回退到 fallback_model（固定免费款），而非自动跟到「当月最新免费款」；严格跟最新款需在切换后手动 hermes model 重选（catalog 已让选择器显示最新款）。
  • 注意：日后若用 hermes model 等 CLI 改模型，必须 export HERMES_HOME=/opt/data，否则 CLI 会在未设 HERMES_HOME 时于 ~/.hermes/config.yaml 生成影子配置、与网关读取的 /opt/data/config.yaml 不一致。

五、验证结果

  • ✅ 两台 hermes-gateway.service active，Telegram 已连（polling 模式，走 sing-box 代理）。
  • ✅ 重启后日志不再出现 No model configured / defaulting to deepseek（旧的 22:xx 时间戳行均为历史）。
  • ✅ 两个 Nous 账号独立（org_id 不同）。
  • ✅ tencent/hy3:free 经 Nous 直连 200；model_catalog 目录经代理可达。
  • ✅ 子代理方案评审 PASS、代码复核 PASS；硬约束未被触碰（tencent 容器、yun1 ai-chat 均在运行）。
  • ⏳ 待办：真实 Telegram 往返验收未完成（见下）。

六、待办 / 后续

  • 真实 Telegram 往返验收：用户需在 Telegram 给两个 bot 各发一条消息——yun1 @feng_hermes1_bot、tencent @feng_hermes2_bot（允许 chat 5359999791）——确认网关这次用 model=tencent/hy3:free 调用成功并回复（而非 404 credits）。发完让我拉日志确认。 ✅ 2026-08-14
  • 若某日 tencent/hy3:free 不再免费：先手动 hermes model 在免费款里重选；或依赖 fallback_model 回退到 stepfun/step-3.7-flash:free。
  • 可选：把 jp 的其余网关相关配置（telegram 富文本、cron 等）按需同步到云上（当前云上仅最小配置，telegram token 走 .env，已正常工作）。

七、关键定位速查

  • 网关配置真路径：/opt/data/config.yaml（CLI 路径是 .hermes/config.yaml，两处不同，别混）。
  • Nous 推理端点：https://inference-api.nousresearch.com/v1，bearer 用 Nous agent_key（NAS invoke JWT）。
  • 代理：127.0.0.1:7890（sing-box mixed）。直连 Nous 推理在云上可能被拦，必须走代理。
  • Telegram Bot API 验证：curl -x 127.0.0.1:7890 https://api.telegram.org/bot<token>/getMe。

八、完整部署过程时间线（两台云服务器，含细节）

目标：在 yun1（121.41.*.*，admin）与 tencent（124.222.*.*，root）各部署一套 Hermes Agent 网关，绑定 两个相互独立的 Nous 官方免费账号（各自独立免费额度），通过 Telegram 收发，egress 走 sing-box 代理 127.0.0.1:7890。参考机为本地 NAS jp（192.168.*.*，已配好 Hermes + 免费模型自动切换）。 硬约束（全程未违反）：不得影响 tencent 既有容器服务（omniroute/codex-box 等）；不得影响 yun1 的 ai-chat 前后端容器。

阶段 0：环境准备

  • 两台均新建 Hermes venv /opt/hermes：yun1 为 Python 3.12，tencent 为 Python 3.11（standalone）。HERMES_HOME=/opt/data，工作目录 /opt/data。
  • sing-box 代理：两台均在本机 127.0.0.1:7890 提供 mixed 入站（vless）。yun1 把 sing-box 从旧版升到 v1.13.18；tencent 已有。
  • Telegram bot（来自 @telegram BOT.txt）：
    • hermes1 = yun1 → @feng_hermes1_bot（id 8880356226:xxxx）
    • hermes2 = tencent → @feng_hermes2_bot（id 8642117385:xxxx）
    • 允许的用户 chat：5359999791（unixcs1）。

阶段 1：安装 Hermes + 建立网关服务

  • pip install hermes-agent（或等价于在 venv 装 hermes_cli），生成 /opt/hermes/bin/hermes 与 python -m hermes_cli.main。
  • 编写 systemd 单元 hermes-gateway.service：User=hermes、WorkingDirectory=/opt/data、Environment=HERMES_HOME=/opt/data、EnvironmentFile=/opt/data/.env、ExecStart=/opt/hermes/bin/python -m hermes_cli.main gateway run；After=sing-box.service（仅排序，不触发重启）。
  • /opt/data/.env（属主 hermes，权限 600）含：HTTP_PROXY/HTTPS_PROXY=http://127.0.0.1:7890、NO_PROXY=localhost,127.0.0.1,::1、`TELEGRAM_BOT_

相关： 00-索引-AI工程索引 8.16 公众号落盘改造与hermes手动发布衔接

关系图谱

反向链接