40-故障排查-常见问题与解决方案

40 · 故障排查——常见问题与解决方案小刘的 Hermes 突然出了问题：发送指令后，Agent 一直卡在"正在思考"状态，等了五分钟也没有输出。他试着重启、重装，问题依旧。到底发生了什么？是模型问题？网络问题？还是配置问题？如果有一个系统性的排查方法，从问题现象到根因定位再到解决方案——这篇故障排查指南就是你的 Hermes 急救手册。一、诊断利器当 Hermes 出现异常时，第一个应该使用的工具是hermes doctor。它是一个全自动诊断命令，可以快速排查大部分常见问题。运行诊断：hermes doctor诊断内容：hermes doctor会逐一检查以下项目：环境检查：操作系统版本、Python 版本、Node.js 版本（如果需要）是否满足最低要求安装完整性：检查是否有缺失的依赖包或损坏的文件配置检查：验证配置文件（config.yaml）的语法和必填字段Provider 连接：尝试连接你配置的 Provider，验证 API 密钥是否有效网络连通性：检查是否能正常访问必要的网络资源模型可用性：验证配置的模型是否对当前 API 密钥可用技能完整性：检查所有安装的 Skill 是否正常加载数据库状态：检查 FTS5 索引和 Honcho 数据库是否损坏输出解读：诊断结果会分项显示：✅（正常）、⚠️（警告，不影响使用但建议关注）、🔴（错误，需要处理）。对于标记为 🔴 的项目，hermes doctor会附带修复建议，大多数情况下你可以直接按照建议操作。定期检查：建议每周运行一次hermes doctor，尤其是在升级 Hermes 版本或修改配置后。预防性检查可以避免很多问题的发生。二、常见场景故障下面是使用 Hermes 过程中最常见的故障及其解决方案。故障一：Provider认证失败现象：启动时提示 “authentication failed” 或 “invalid API key”。