DeepAI Paper Hermes Agent 教程,Hermes Gateway 与消息平台,Hermes 安全、网络与代理,Hermes 终端、Docker 与安装 Hermes Agent 跨平台排错：Windows 代理 502、Docker 后端残留和飞书表格源码显示

Hermes Agent 跨平台排错：Windows 代理 502、Docker 后端残留和飞书表格源码显示

2026年5月14日2026年5月14日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 下午2:45
Categories:

Hermes Agent 的 issue 里，有一类问题很有意思：它们看起来像模型坏了，实际是运行环境、平台适配或本地网络把链路搞歪了。

比如：

  • 明明设置了 terminal.backend=local，但 Discord 里执行终端还是跑进 Docker；
  • Windows 系统代理一开，主对话正常，但 title generation、context compression 这类辅助请求报 502；
  • 飞书里让 Hermes 输出 Markdown 表格，结果用户看到的是 | col1 | col2 | 源码；
  • Web Dashboard 的语言下拉框跑到视口外。

这些问题和 DeepAI、OpenAI-compatible API、模型质量关系不大。它们更像 Hermes 作为“跨平台 Agent”时必须面对的现实：Windows、Docker、代理、Discord、飞书、Web UI，每层都可能有自己的坑。

这篇继续基于 Hermes GitHub Issues 做一篇跨平台排错笔记。

先建立一个判断：模型正常，不等于 Hermes 全链路正常

很多人接入 DeepAI API 中转站后，会把 Hermes 的所有异常都往模型层排。

但 Hermes 不是普通聊天客户端。它包括：

平台入口：Discord / 飞书 / Web UI / Open WebUI
Gateway：消息接收、投递、线程、重试
Agent：任务规划、工具调用、上下文管理
Terminal：local / Docker / sandbox
Provider：DeepAI / Custom Endpoint / OpenAI-compatible API
Auxiliary：标题生成、压缩、搜索、后台任务

所以即便 DeepAI 直连完全正常，下面这些问题仍然可能发生：

  • 终端执行环境不是你以为的那个；
  • localhost 请求被系统代理劫走；
  • 平台不支持某种 Markdown；
  • Web UI 组件样式溢出；
  • 后台辅助请求和主对话走的客户端配置不同。

排错第一步不是换模型，而是问：这个异常发生在哪一层？

Issue 1：terminal.backend=local，但工具执行仍然跑进 Docker

相关 Issue：

https://github.com/NousResearch/hermes-agent/issues/25402

这个问题发生在 Windows + Discord Gateway 场景。

用户把终端后端从 Docker 切回 local，配置界面显示：

terminal:
  backend: local
  cwd: .

但在 Discord 里让 Hermes 执行终端诊断时，实际仍然进入 Docker / Linux 环境。

典型表现包括：

pwd 显示 /root
存在 Docker overlay filesystem 痕迹
像是在容器里
Windows hermes CLI 不可见

最后的 workaround 是：把 config.yaml 里残留的 Docker 相关 terminal 配置删掉，然后重启 gateway，终端工具才正确回到 Windows local MSYS 环境。

修复后的诊断结果类似：

pwd: /c/Users/Vineel
HOME: /c/Users/Vineel
uname: MINGW64_NT...
whoami: Vineel
/.dockerenv: not present
hermes: /c/Users/Vineel/AppData/Local/hermes/hermes-agent/venv/Scripts/hermes
terminal.backend: local

这个 issue 的排错价值

它说明一件事：配置界面显示 local，不代表实际 tool execution 一定在 local。

尤其是你曾经切换过：

local → Docker → local

那么 config.yaml 里可能还残留：

terminal.docker_image
terminal.docker_volumes
其他 Docker-only terminal keys

这些 stale keys 可能继续影响实际执行。

怎么自查

从 Discord 或 Gateway 会话里让 Hermes 执行：

pwd
uname -a
whoami
hostname
mount | head
command -v hermes
test -f /.dockerenv && echo docker || echo not-docker

如果你以为是 Windows local，但看到 /root、Linux overlay、/.dockerenv，就不要再怀疑 DeepAI 或模型了。

这是 terminal backend / config residue 问题。

处理建议

  • 打开 Hermes config.yaml；
  • 确认 terminal.backend 是 local；
  • 删除 Docker 后端专属残留配置；
  • 重启 gateway；
  • 再用上面的命令确认真实执行环境。

如果你在生产环境里跑 Hermes，我建议每次切换 terminal backend 后，都做一次真实环境探针，而不是只看配置 UI。

Issue 2：Windows 系统代理导致 auxiliary client 本地请求 502

相关 Issue：

https://github.com/NousResearch/hermes-agent/issues/25319

这个问题更隐蔽。

现象是：Windows 开了系统级 HTTP 代理后，Hermes 主对话正常，但 auxiliary LLM calls 失败，比如：

  • title generation；
  • context compression；
  • session search；
  • 其他后台辅助任务。

错误类似：

WARNING agent.title_generator: Title generation failed: Error code: 502

Issue 里的根因分析是：OpenAI Python SDK 底层使用 httpx.Client，并且默认 trust_env=True。这会让 httpx 自动读取 Windows 系统代理设置。

结果就是：本来应该直连 localhost 的请求，也被系统代理接管。

代理无法正确处理 localhost，于是返回：

502 Bad Gateway

这解释了为什么主对话可能正常，而 title generation 失败。

它们可能不是完全同一条客户端路径。

关键判断点

如果你使用的是本地 OpenAI-compatible endpoint，比如：

http://localhost:20128/v1
http://127.0.0.1:xxxx/v1

并且 Windows 开了系统代理，那么要特别小心。

你可以对比：

调用方式结果
curl 直连 localhost200
requests 直连 localhost200
OpenAI SDK 默认 httpx trust_env=True可能走代理，502
httpx.Client(trust_env=False)直连，200

这也是为什么你会觉得“curl 明明通，Hermes 怎么不通”。

因为 curl 和 OpenAI SDK 的代理行为可能不同。

对 DeepAI 用户的提醒

如果你接的是 DeepAI 公网 API：

https://api.deepai.wang/v1

这个 issue 不一定直接命中。

但如果你的链路是：

Hermes → 本地代理 / 本地网关 / 本地转发 → DeepAI

或者：

Hermes auxiliary client → localhost OpenAI-compatible server

那 Windows 系统代理就可能影响 localhost。

这时不要只查 DeepAI Key，要查：

  • Windows 系统代理；
  • HTTP_PROXY / HTTPS_PROXY / NO_PROXY 环境变量；
  • auxiliary client 是否绕过 localhost proxy；
  • 127.0.0.1 和 localhost 是否都在 NO_PROXY 里；
  • Hermes 版本是否已修复 auxiliary client 的 trust_env 行为。

临时处理建议

可以尝试：

关闭 Windows 系统代理
或设置 NO_PROXY=localhost,127.0.0.1
或避免 auxiliary endpoint 指向 localhost
或升级到包含 trust_env=False 修复的版本

如果你自己维护代码，针对 localhost base_url 创建 httpx.Client(trust_env=False) 是更干净的方向。

Issue 3：飞书 Markdown 表格显示成源码，不是模型格式错

相关 Issue：

https://github.com/NousResearch/hermes-agent/issues/25452

这个问题发生在 Feishu / 飞书 channel。

用户让 Hermes 输出表格，例如：

请用表格对比 Python 和 Go 的特点

结果飞书客户端里看到的是 Markdown 表格源码：

| 特点 | Python | Go |
|---|---|---|
| 语法 | 简洁 | 工程化 |

这很容易让人以为：模型不会正确输出表格。

但 Issue 里的根因不是模型，而是飞书消息类型对 Markdown table 的支持问题。

Hermes 的 Feishu adapter 当前会检测 Markdown 表格，然后 fallback 到 text 类型，避免 post 类型渲染为空白。副作用就是：用户看到 raw markdown。

Issue 里提到的改进方向是使用飞书 Interactive Cards：

  • 解析 AI response 中的 Markdown table；
  • 分离 prose segment 和 table segment；
  • 把 table 转成飞书 card table components；
  • 把普通文本保留为 card markdown elements；
  • 超过限制时 fallback 到 text。

排错价值

这类问题的重点是：平台 Markdown 能力不一样。

Discord、飞书、Telegram、微信、Slack 对 Markdown 的支持都不完全一样。

同一段模型输出，在网页里好看，在飞书里可能变源码，在微信里可能丢格式，在 Discord 里可能超长被切块。

所以如果 DeepAI 返回的原始内容是正确 Markdown，而飞书展示不对，那问题在 channel renderer，不在模型。

实用建议

在飞书场景里，可以减少表格依赖，改成：

请用项目符号对比，不要用 Markdown 表格

或者让 Hermes 在 Feishu channel 默认使用：

- 维度：语言生态
  - Python：数据科学、脚本、AI 强
  - Go：后端、云原生、并发强

这比强行输出表格更稳。

如果你要做团队知识库或日报，建议优先用列表、编号、短段落，而不是大表格。

Issue 4：Web Dashboard 下拉框跑出视口，是前端 UI 问题

相关 Issue：

https://github.com/NousResearch/hermes-agent/issues/25466

这个 issue 是 Web Dashboard 的语言切换下拉框显示在 viewport 底部之外。

场景大概是：

run hermes dashboard
cd web && npm run dev
点击 Gb/en 语言按钮
下拉框向下展开，超出视口

这类问题对模型调用没有任何影响，但它会影响用户对产品稳定性的感受。

如果你在 Hermes Web UI 里遇到按钮、下拉框、面板显示异常，不要优先动 DeepAI 配置，也不要怀疑 API 中转站。

它就是前端组件定位问题。

排查方向是：

  • 浏览器窗口高度；
  • popover / dropdown placement；
  • CSS overflow；
  • 是否应该自动 flip 到上方；
  • Hermes Web UI 版本。

一个跨平台排错表

现象更可能的层级自查方法
terminal.backend=local 但 pwd 是 /rootTerminal backend / Docker 残留配置查 /.dockerenv、uname -a、config.yaml
主对话正常，title generation 502Auxiliary client / Windows proxy / localhost查系统代理、NO_PROXY、localhost base_url
飞书表格显示 Markdown 源码Feishu renderer / message type换列表输出，查 Feishu adapter
Dashboard 下拉框超出视口Web UI 前端缩放窗口、更新版本、查 CSS placement
DeepAI curl 正常但 Hermes 工具异常Hermes 其他层不要先改模型，按链路分层查

这张表的核心是：异常在哪里发生，就查哪一层。

不要因为 Hermes 最后会调用模型，就把所有问题都归给模型。

DeepAI 接 Hermes 时的稳定排错顺序

如果你正在用 DeepAI API 中转站作为 Hermes 的 custom endpoint，可以按这个顺序排：

1. 先验证 DeepAI 本身

curl https://api.deepai.wang/v1/chat/completions \
  -H "Authorization: Bearer YOUR_DEEPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "reply ok"}]
  }'

这一步只验证上游模型服务。

2. 再验证 Hermes provider 配置

确认：

Base URL: https://api.deepai.wang/v1
API Key: DeepAI 控制台里的 Key
Model ID: DeepAI 控制台里的真实模型

不要把 Base URL 写成 /v1/chat/completions。

3. 工具异常看 terminal backend

如果是文件、终端、命令执行异常，去查 local / Docker / sandbox，不要先换模型。

4. 后台任务异常看 auxiliary client

title generation、compression、session search 这类失败，不一定影响主对话，也不一定是 DeepAI 错。

5. 平台展示异常看 renderer

Discord、飞书、微信、Open WebUI 展示不一致时，先看平台消息格式能力。

这些 issue 给 Hermes 用户的启发

Hermes 的价值在于它不是普通聊天框，而是能跑工具、接平台、做长任务、保留上下文的 Agent。

但代价是：排错必须更工程化。

你需要知道：

  • 模型层只负责生成；
  • provider 层负责 API 兼容和鉴权；
  • auxiliary client 可能有独立请求路径；
  • terminal backend 决定工具到底跑在哪；
  • gateway 决定消息怎么进出平台；
  • renderer 决定用户最终看到什么格式。

DeepAI API 中转站可以解决的是模型接入和 OpenAI-compatible API 统一入口问题。

但 Docker 残留配置、Windows 代理劫持 localhost、飞书表格渲染，这些要在 Hermes 自己的运行环境和平台适配层解决。

把层级分清，问题就不难。

相关 Issue

terminal.backend=local 仍可能使用 Docker：

https://github.com/NousResearch/hermes-agent/issues/25402

Windows 系统代理导致 auxiliary client localhost 请求 502：

https://github.com/NousResearch/hermes-agent/issues/25319

飞书 Markdown 表格显示为源码：

https://github.com/NousResearch/hermes-agent/issues/25452

Web Dashboard 语言下拉框超出视口：

https://github.com/NousResearch/hermes-agent/issues/25466

DeepAI API 中转站：

https://api.deepai.wang/

Hermes 接入 DeepAI 教程：

Hermes Agent 接入 DeepAI 教程：用 Custom Endpoint 配 OpenAI Compatible API

Hermes Issues 分层排错：

Hermes Agent Issue 观察：Discord 重复回复、Cloudflare 403 和长任务心跳为什么容易误判

总结

Hermes 的跨平台问题，常常不是模型问题。

Windows 系统代理可能让 localhost auxiliary 请求变成 502。

Docker terminal 配置残留可能让你以为自己在 local，实际工具还跑在容器里。

飞书 Markdown 表格显示源码，是平台 renderer 能力问题。

Web Dashboard 下拉框跑出屏幕，是前端 UI 问题。

如果你用 DeepAI 接 Hermes，最稳的方式是：先验证 DeepAI API，再验证 Hermes provider，然后按终端、辅助请求、Gateway、平台展示逐层排查。这样不会把本来正常的 DeepAI 配置改坏，也能更快定位真正的问题。

Related Post

Hermes Docker 里读不到 GITHUB_TOKEN？~/.hermes/.env 环境变量转发排错指南Hermes Docker 里读不到 GITHUB_TOKEN？~/.hermes/.env 环境变量转发排错指南

2026年5月14日2026年5月14日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 下午6:07

Hermes config set GITHUB_TOKEN 后，Docker terminal 里仍读不到环境变量？这可能是 Docker exec 只转发当前 shell env，却没加载 ~/.hermes/.env。本文解释 GITHUB_TOKEN、docker_forward_env、~/.gitconfig 挂载和容器内 printenv 排查方法。

Read MoreRead More

Hermes Agent 常见问题排查：从 GitHub Issues 看 403、502、Docker 后端和自定义接口坑Hermes Agent 常见问题排查：从 GitHub Issues 看 403、502、Docker 后端和自定义接口坑

2026年5月14日2026年5月14日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 下午1:55

翻看 Hermes Agent GitHub Issues 后整理的排错复盘：Custom Endpoint 403、后台 review agent、Windows localhost 502、terminal.backend 残留 Docker 配置、Feishu 表格渲染等问题。

Read MoreRead More

钥匙明明在 .env，Hermes 却说找不到：credential_pool 只摸口袋不看保险箱钥匙明明在 .env，Hermes 却说找不到：credential_pool 只摸口袋不看保险箱

2026年5月15日2026年5月15日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 上午12:47

Hermes 把 API key 放在 ~/.hermes/.env 里却仍报 No API key found？本文复盘 #15932：credential_pool._seed_from_env 只看 os.environ，auth 解析也没有 fallback 到 credential pool，导致 OpenAI-compatible provider 的认证链路断掉。

Read MoreRead More