Hermes Agent 代理网络设置 + Fallback 降级

2026-10-13

记录时间：2026-06-19 最后更新：2026-06-19 适用环境：Windows 10（git-bash/MSYS） Hermes Home：~/AppData/Local/hermes/

概述

Hermes Agent 没有内置的 proxy 配置项（无 hermes config set proxy 类的命令）。但 Hermes 底层使用 Python 的 httpx / aiohttp / requests 等标准 HTTP 库，这些库都遵循标准的代理环境变量。

因此，设置代理的方式就是通过环境变量，让 Hermes 的所有 API 请求走代理。

适用场景

  • 需要将 LLM API 请求（OpenAI / OpenRouter 等）走代理网络
  • 本地网络可以直接访问某些 API（如 DeepSeek），不需要走代理
  • 需要 GPT 和 DeepSeek 自动切换的容灾方案
  • 需要使用分流代理（Clash / v2ray / SSR / sing-box 等）

当前架构

┌─────────────────────────────────────────────────────┐
│                    Hermes Agent                      │
│                                                      │
│  主模型: gpt-5.4-mini (openai-codex, OAuth)         │
│    └─ HTTP_PROXY=http://127.0.0.1:7897 → OpenAI     │
│                                                      │
│  失败时自动切换 ↓                                    │
│                                                      │
│  Fallback: deepseek-v4-flash (custom:ds-hermes)     │
│    └─ NO_PROXY → 直连 api.deepseek.com              │
└─────────────────────────────────────────────────────┘

核心思路：GPT 必须走代理（直连不通），当 GPT 因代理故障 / 限流 / 超时而失败时，Hermes 内置的 fallback 机制自动切换到 DeepSeek（直连）。

配置方法

Step 1：写入 .env（代理设置）

实际路径：~/AppData/Local/hermes/.env

HTTP_PROXY=http://127.0.0.1:7897
HTTPS_PROXY=http://127.0.0.1:7897
NO_PROXY=localhost,127.0.0.1,::1,api.deepseek.com

注意： NO_PROXY 中加入了 api.deepseek.com，这样 DeepSeek 的请求绕过代理直连。当代理故障导致 GPT 请求失败时，fallback 到 DeepSeek 仍可正常工作。

生效方式： - CLI 模式：退出重进，或在对话内执行 /reload - Gateway 模式：hermes gateway restart

Step 2：配置 Fallback Provider

通过 CLI 添加（推荐）：

hermes fallback add
# → 选 provider: custom:ds-hermes
# → 选 model: deepseek-v4-flash

或直接编辑 config.yaml：

fallback_providers:
  - provider: custom:ds-hermes
    model: deepseek-v4-flash

同时建议降低重试次数以便快速降级：

agent:
  api_max_retries: 1   # 失败 1 次即切换 fallback，避免空转等待

当前生效配置（2026-06-19）

项目 值
主模型 gpt-5.4-mini (openai-codex, OAuth)
代理 HTTP_PROXY=http://127.0.0.1:7897（GPT 对话、浏览器、搜索）
Fallback deepseek-v4-flash (provider: deepseek, 直连)
NO_PROXY localhost,127.0.0.1,::1,api.deepseek.com
api_max_retries 1（失败即切换，避免空转）
auxiliary.web_extract provider: deepseek（Web 搜索内容处理走 DeepSeek 直连）

工作流程

GPT 对话请求
  └─ 通过代理 (7897) → OpenAI Codex API ✅

Web 搜索 / 浏览器请求
  ├─ HTTP 获取 → 通过代理 (7897) ✅
  └─ 内容处理 → DeepSeek 直连 ✅（auxiliary.web_extract）

GPT 故障时：
  ├─ api_max_retries=1 → 1次重试后触发 fallback
  └─ Fallback → DeepSeek 直连（NO_PROXY 绕过代理） ✅

验证代理是否生效

测试代理连通性

# 测试代理是否在监听
netstat -ano | grep 7897

# 测试通过代理访问 OpenAI
curl -x http://127.0.0.1:7897 -s -o /dev/null -w "OpenAI via proxy: %{http_code}\n" \
  --connect-timeout 10 https://api.openai.com/v1/models
# 返回 401 表示代理正常（未传递 API Key）

测试 NO_PROXY 直连

# 测试 DeepSeek 直连（绕过代理）
curl -s -o /dev/null -w "DeepSeek direct: %{http_code}\n" \
  --connect-timeout 10 https://api.deepseek.com/v1/models
# 返回 401 表示直连正常

查看 Hermes 日志

cat ~/AppData/Local/hermes/logs/gateway.log | grep -i "proxy\|connect\|timeout\|fallback"
cat ~/AppData/Local/hermes/logs/errors.log | grep -i "proxy\|connect\|timeout\|fallback"

Fallback 机制详解

触发条件（自动生效，无需手动干预）

触发条件 行为
429 Rate Limited 自动切下一个 fallback
402 Billing/Quota 耗尽 自动切下一个 fallback
5xx 服务端错误 自动切下一个 fallback
连接超时/网络错误 自动切下一个 fallback
空回复/格式错误 自动切下一个 fallback
Safety Refusal 自动切下一个 fallback
Token 耗尽/授权失效 自动切下一个 fallback

相关 CLI 命令

hermes fallback list      # 查看当前 fallback 链
hermes fallback add       # 交互式添加 fallback provider
hermes fallback remove    # 删除某个 fallback
hermes fallback clear     # 清空全部 fallback

Fallback 链支持多级

fallback_providers:
  - provider: custom:ds-hermes
    model: deepseek-v4-flash
  - provider: openrouter
    model: openai/gpt-4o

按顺序尝试，直到有一个成功。

代理端口参考

代理软件 默认本地端口
Clash / Clash Meta 7890
v2rayN / X-ray 10808 / 10809
sing-box 2080
SSR 1080
ProxyChains 9050

常见问题排查

Q1：设置代理后 API 请求变慢或超时

可能原因： - 代理服务器未正常运行 - 代理服务器网络不稳定 - 代理端口写错

排查： 1. netstat -ano | grep 7897 确认代理在监听 2. curl -x http://127.0.0.1:7897 -v https://api.openai.com/v1/models，观察 CONNECT 阶段输出 3. 确认 api_max_retries 为 1，避免失败后空转等待

Q2：设置代理后本地服务异常

原因：NO_PROXY 未设置或设置不完整。

解决：确保包含 localhost,127.0.0.1,::1。

Q3：代理故障，GPT 和 DeepSeek 都用不了

原因：NO_PROXY 中未加入 api.deepseek.com，导致 DeepSeek 请求也被送往已故障的代理。

解决：在 NO_PROXY 中加入 api.deepseek.com，这样 DeepSeek 的请求绕过代理直连。

Q4：Fallback 没有生效

排查： 1. hermes fallback list 确认 fallback 链配置正确 2. 检查日志中是否有 fallback 关键字 3. 确认 fallback provider 的 API Key 有效

恢复方案

清除代理配置

# 从 .env 中移除代理行
cat ~/AppData/Local/hermes/.env | grep -v -i proxy > ~/AppData/Local/hermes/.env.clean
mv ~/AppData/Local/hermes/.env.clean ~/AppData/Local/hermes/.env

清除 Fallback 配置

hermes fallback clear

或编辑 config.yaml，将 fallback_providers 设为空列表：

fallback_providers: []

恢复 api_max_retries

hermes config set agent.api_max_retries 3

恢复后重启

hermes gateway restart

参考文档

  • Hermes 环境变量配置：https://hermes-agent.nousresearch.com/docs/reference/environment-variables
  • Hermes 配置文档：https://hermes-agent.nousresearch.com/docs/user-guide/configuration
  • Hermes Fallback Providers（官方文档）：https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers
  • .env 文件位置：~/AppData/Local/hermes/.env
  • config.yaml 位置：~/AppData/Local/hermes/config.yaml
  • 代理软件配置请参考各自官方文档

修改记录

日期 修改内容
2026-06-19 初始创建，基础代理设置
2026-06-19 更新实际 Hermes Home 路径 (~/AppData/Local/hermes/)
2026-06-19 代理端口改为 7897
2026-06-19 新增 Fallback Provider 配置章节
2026-06-19 新增 GPT + DeepSeek 混合架构说明
2026-06-19 新增 NO_PROXY 绕过 DeepSeek 方案
2026-06-19 新增恢复方案

← 返回文章列表