跳转到内容

排错路径

排查 Hermes 时,最重要的是不要一次改太多东西。它横跨 Python 环境、模型 provider、prompt、工具、文件系统、gateway 和长期状态;乱换模型、重装、改 prompt、开关工具,很快就不知道哪个动作产生了变化。

从最小命令开始:

Terminal window
command -v hermes
hermes --help
python -m pip show hermes-agent

如果命令层没问题,再进入一个低风险目录跑最小会话。不要直接用失败的大任务做排查样本。

层典型症状先做什么
安装command not found、import error查 PATH、Python 版本、包位置。
Provider鉴权失败、模型不存在、限流重新跑 hermes model,确认 key、账号和模型名。
模型质量输出乱、工具调用差换小任务测试,比较同一 prompt 在不同模型下表现。
Prompt/context忽略项目规则、带入旧假设检查 context files、memory、skills。
工具路径错、命令失败、API 报错在 agent 外单独运行工具或命令。
文件状态改错文件、diff 异常看 pwd、git status --short、Git diff。
Gateway收不到消息、串 session查 token、allowlist、session routing、gateway logs。
Cron/automation后台跑错、没人知道失败查 owner、日志、schedule、配置刷新和停止路径。

排查顺序通常从左到右。越靠后,变量越多。

常见原因是 provider 配置不通:

  1. 重新运行 hermes model。
  2. 确认 provider 账号可用。
  3. 确认模型名仍然存在。
  4. 检查 API key 或 OAuth 是否过期。
  5. 如果用了 OpenAI-compatible endpoint,在 agent 外发一个最小请求。

不要先改复杂 prompt。模型路径没通时,prompt 再好也没用。

按来源找:

  • 只在当前对话出现:检查 session。
  • 每个新会话都出现:检查 memory 或全局 context。
  • 只在某个项目出现:检查 AGENTS.md、.hermes.md、CLAUDE.md 等。
  • 只在某类任务出现:检查对应 skill。

删除坏来源比在 prompt 里反复否定更可靠。

工具失败要看真实错误,而不是只看最终回答:

Terminal window
pwd
git status --short
which node
which python

如果 Hermes 要运行某条命令,先在终端手动跑一个只读或 dry-run 版本。路径、权限、依赖和网络问题应该在 agent 外也能复现。

远程和后台问题要额外关注“哪个进程在运行”:

  • 是否加载了最新配置。
  • token 或 allowlist 是否正确。
  • 当前消息进入哪个 session。
  • 长期进程是否仍在使用旧版本。
  • 日志在哪里,是否自动脱敏。
  • 如何安全停止并重启。

很多 gateway 问题看起来像“agent 不理我”,实际是 bot token、平台权限、session 路由或服务进程状态问题。

Hermes version:
Install method:
Python version:
OS and shell:
Provider:
Model:
Command or prompt:
Working directory:
Expected result:
Actual result:
Relevant log or error:

这份信息足够短,但能让别人真正帮你判断层次。