【Hermes Agent 进阶教程】彻底解决本地大模型/慢速 API 的请求超时问题
💡 前言：使用默认超时配置会产生的问题
Hermes Agent 默认的超时配置主要针对响应迅速的云端商业 API 设计。当接入本地部署的大模型（如 Ollama、vLLM、LM Studio 等）或处于复杂网络环境时，使用默认配置通常会导致以下问题：
- 本地推理直接报错中断：本地模型在处理长上下文（Prefill 阶段）或复杂逻辑时，首字响应和整体生成耗时较长，极易触发
ReadTimeout，导致 Agent 直接抛出超时错误并终止任务。 - 流式输出意外截断：在流式生成（Stream）模式下，如果本地显卡算力受限，导致两个 Token 之间的生成间隔超过默认阈值，底层连接会被强行掐断，导致模型回复只有一半。
- Channel 消息收发失败：在弱网环境或使用代理的网络下，默认极短的 HTTP 超时会导致 Agent 无法成功连接 Channel 服务器，拉取不到用户指令或无法发送长文本/文件回复。
- 高并发下连接池耗尽：当 Agent 同时处理多个工具调用或群组内多人同时 @ 时，默认的连接池等待时间过短，容易引发
PoolTimeout报错。
为了解决这些问题，我们需要为本地大模型和 Channel 交互配置“超长待机”模式。本文将详细拆解8 个核心的超时环境变量，教你如何彻底告别超时焦虑！
🔑 核心参数详解
我们将这 8 个参数分为两大类：大模型 API 交互超时和通信超时。
(注：以下配置值1800代表 1800秒，即 30分钟，对于绝大多数本地模型生成任务已经极其充裕。)
第一类：大模型 API 交互超时（解决模型思考慢、生成慢）
这类参数控制 Hermes 与你的大模型后端（如 OpenAI 兼容接口）之间的连接耐心。
| 环境变量名 | 作用解析 | 为什么本地模型需要它？ |
|---|---|---|
HERMES_API_TIMEOUT | API 请求总超时控制从发出请求到收到完整响应的最大总时间。 | 本地模型处理超长上下文（Prefill 阶段）或生成极长文本时，总耗时可能超过几分钟。设置 1800 秒给足模型整体计算时间。 |
HERMES_API_CALL_STALE_TIMEOUT | API 调用陈旧超时防止连接变成“僵尸状态”的强制熔断机制。 | 如果本地模型进程意外卡死，不再返回任何数据，此参数会在 30 分钟后强制清理无效连接，释放 Agent 资源。 |
HERMES_STREAM_READ_TIMEOUT | **流式读取超时 (核心!)**在流式输出（Stream=True）模式下，两个 Token（字）之间允许的最大等待间隔。 | 本地显卡算力有限时，生成速度可能只有几个 token/s，遇到复杂推理甚至会有几秒到十几秒的“卡顿”。此参数防止因单次吐字慢而被误判为断线。 |
HERMES_STREAM_STALE_TIMEOUT | 流式陈旧超时整个流式连接的生命周期上限。 | 确保即使模型在持续缓慢地输出，整个流式会话最长也能保持 30 分钟的活跃状态而不被底层网络库掐断。 |
第二类：通信超时（解决消息收发网络波动）
如果你使用 channel 作为 Hermes 的交互前端，以下参数控制 Hermes 与 channel 服务器之间的网络连接稳定性。
| 环境变量名 | 作用解析 | 为什么需要调整？ |
|---|---|---|
HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT | TCP 连接建立超时与 channel 服务器建立初始连接的最大等待时间。 | 在某些网络环境下（如需通过代理访问 TG），握手过程可能较慢，增加此值防止连接初始化失败。 |
HERMES_TELEGRAM_HTTP_READ_TIMEOUT | 读取响应超时等待 Telegram 服务器返回数据（如接收用户消息）的最大时间。 | 防止因网络波动导致 Agent 无法及时拉取到用户的最新指令。 |
HERMES_TELEGRAM_HTTP_WRITE_TIMEOUT | 写入/发送超时向 Telegram 服务器发送数据（如回复长文本、图片）的最大时间。 | 当 Agent 生成了超长回复或大文件需要上传时，给予充足的发送时间，避免发送中途断开。 |
HERMES_TELEGRAM_HTTP_POOL_TIMEOUT | 连接池获取超时当并发请求过多时，等待连接池中空闲连接的最大时间。 | 在群组中多人同时 @Agent，或 Agent 同时处理多个工具调用时，防止因连接池耗尽而报错。 |
🛠️ 实战配置步骤
1. 修改环境变量文件
找到你的 Hermes Agent 配置文件，通常位于用户目录下的~/.hermes/.env（如果是 Docker 部署，则是docker-compose.yml的environment部分或挂载的.env文件），自定义 agent 在 profile 文件夹中 agent 名文件下的.env。
使用文本编辑器打开它，并追加以下内容：
# ==========================================# Hermes Agent 本地大模型/慢速 API 防超时配置# 数值单位：秒 (1800秒 = 30分钟)# ==========================================# 1. 大模型 API 超时设置HERMES_API_TIMEOUT=1800HERMES_API_CALL_STALE_TIMEOUT=1800HERMES_STREAM_READ_TIMEOUT=1800HERMES_STREAM_STALE_TIMEOUT=1800# 2. channel 通信超时设置HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT=1800HERMES_TELEGRAM_HTTP_READ_TIMEOUT=1800HERMES_TELEGRAM_HTTP_WRITE_TIMEOUT=1800HERMES_TELEGRAM_HTTP_POOL_TIMEOUT=18002. 重启 Hermes 服务
环境变量修改后，必须重启服务才能生效：
- 命令行部署：停止当前进程，重新运行
hermes启动命令。 - Docker 部署：执行
docker compose down然后docker compose up -d。
⚠️ 避坑指南：为什么设置了还是超时？
如果你配置了上述参数，但依然遇到超时断开，请务必排查以下“隐藏杀手”：
坑点：Nginx 反向代理的“背刺”（最常见！）
如果你在本地模型（如 Ollama）前面套了Nginx做反向代理（为了配置域名或 HTTPS），Nginx 默认的proxy_read_timeout只有60秒！
结果就是：Hermes 愿意等 30 分钟，但 Nginx 在第 60 秒就把连接掐断了。
解决办法：修改 Nginx 配置文件，增加以下参数并reload：
location / { proxy_pass http://127.0.0.1:11434; # 你的模型地址 proxy_read_timeout 1800s; proxy_send_timeout 1800s; proxy_connect_timeout 1800s; send_timeout 1800s; }