第七章：常见故障模式与排查指南

在部署和使用 Hermes Agent 过程中，尤其是涉及网络连接或权限调用时，可能会遇到一些常见报错。以下是标准的排查（Troubleshooting）流程与处理建议：

7.1 快速诊断命令

在排查任何疑难杂症前，建议优先在终端依次运行以下指令进行健康检查：

• hermes doctor：核心排查工具，会运行综合诊断程序并给出明确的修复建议。
• hermes config check：检查配置文件格式是否正确，环境变量是否冲突。
• hermes model：检查模型 API 配置以及连通性是否正常。

7.2 安装与环境故障

• 报错：hermes: command not found
  • 原因：安装完成后，当前终端窗口未加载环境变量。
  • 修复：执行 source ~/.bashrc（Zsh 用户执行 source ~/.zshrc），或者直接关闭当前终端窗口重新打开。
• 报错：WSL Connection Refused / OLLAMA 连通失败 (Windows 用户)
  • 原因：WSL 与 Windows 宿主机网络隔离，Ollama 未开放监听端口。
  • 修复：在 Windows 端设置环境变量 OLLAMA_HOST=0.0.0.0，并在 Windows Defender 防火墙中手动放行 11434 端口入站规则。

7.3 API 与模型认证故障

• 报错：401 Unauthorized / API Key Invalid
  • 原因：密钥拼写错误、已过期，或者所选 Provider 与填入的 Key 不匹配（例如用 OpenAI 的 Key 连了 OpenRouter 的接口）。
  • 修复：运行 hermes config edit 或直接修改 ~/.hermes/.env 核对密钥，重新运行 hermes model 确认选择。
• 报错：429 Too Many Requests (速率限制)
  • 原因：短时间内调用过于频繁，或者输入的上下文 Token 超出了模型支持的单次限制。
  • 修复：对于长文本分析，先使用 Summarizer 技能提取摘要，或切换至拥有 128k+ 窗口的长文本模型（如 Kimi / Claude 3）。

7.4 记忆与权限问题

• 故障现象：Agent “记不住”上下文或反复请求权限
  • 原因：~/.hermes/ 目录的读写权限受限，导致 USER.md 和 MEMORY.md 无法保存；或者使用了不可信路径。
  • 修复：确保存储目录有足够的读写权限（执行 chmod 600 ~/.hermes/*）；检查工具审批策略是否设置了 strategy: "remember"。
• 故障现象：高危操作直接执行造成破坏
  • 原因：开启了 /yolo 模式，导致跳过了 execute_shell 等危险操作的拦截。
  • 修复：重启终端或输入 /yolo 关闭该模式，并在进行高风险自动化任务时加上 --checkpoints 实现文件保护回滚。

7.5 网关与自动化 (Gateway & Cron) 故障

• 故障现象：Cron 定时任务未按时触发
  • 原因：Hermes 的后台调度服务（daemon）被系统杀掉或未启动。
  • 修复：运行 hermes cron start 确保守护进程存活，或使用 hermes cron run <id> 强制执行一次查看报错日志。
• 故障现象：钉钉/飞书 机器人消息无响应
  • 原因：网关出口网络受限，或 .env 里的凭证不对。
  • 修复：不要在后台盲调。先停止后台服务，执行 hermes gateway run（前台运行模式），这时候如果报错，错误信息会直接打印在屏幕上，方便定位是鉴权失败还是网络超时。