Hermes_Agent_常见报错代码解析与系统诊断（Doctor命令）排错指南

hermes doctor 是系统性诊断工具，用于检测模型连接、技能加载和安全策略；出现 FAIL 时功能不可信，需结合 --deep、--target memory、--no-cache 等参数定位具体故障。

当你在终端输入 hermes 却收到 command not found，或运行 hermes chat 后卡住无响应、报错信息里反复出现 Failed to load model 或 Connection refused，说明底层环境或配置已出现断裂，必须用 hermes doctor 系统性扫描真实状态，而非凭猜测修改配置文件。

快速验证命令是否真正就位

打开终端，直接执行：
hermes --version

若输出类似 hermes 0.8.0，说明二进制已安装且 PATH 正确；
若提示 command not found，请立即执行 source ~/.bashrc（zsh 用户用 source ~/.zshrc），【这是最常被跳过的一步，90% 的“命令不存在”问题在此解决】；
仍失败则检查 ~/.local/bin 是否在 PATH 中：echo $PATH | grep local。

执行基础健康检查

运行：
hermes doctor

该命令会自动检测模型连接性、技能加载状态、安全策略初始化三项核心能力。
输出中每行以 [PASS] 或 [FAIL] 开头，【只要出现一个 [FAIL]，后续所有功能都不可信】；
常见 [FAIL] 条目如 Model provider unreachable，意味着 API Key 无效或 base_url 格式错误；
若全部显示 [PASS] 但实际仍无法聊天，请进入下一步深度诊断。

启用深度诊断模式定位隐性故障

方法一：全量依赖与技能扫描
hermes doctor --deep

此模式会递归检查 ~/.hermes/skills/ 下每个技能的 manifest.yaml 是否语法合法、依赖声明是否完整、Python 模块能否成功 import。若某技能缺失 __init__.py 或引用了未安装的包，此处会明确标出路径和错误类型。

方法二：聚焦记忆模块校验
hermes doctor --target memory

专用于排查会话历史丢失、上下文截断异常等问题。它会读取 ~/.hermes/state.db，输出最近 5 条会话摘要及时间戳哈希值。若返回 No records found，说明持久化存储未启用或数据库损坏，需重置：rm ~/.hermes/state.db。

方法三：强制跳过缓存验证原始配置
hermes doctor --no-cache

当修改了 config.yaml 却始终不生效，极可能是旧缓存干扰。此参数让诊断完全绕过内存缓存，直读磁盘文件。若 --no-cache 下显示 [FAIL] 而默认模式下是 [PASS]，说明你正在编辑的配置文件根本不是 Hermes 实际加载的那个路径。

生成离线诊断快照供协作分析

第一步：生成结构化诊断包
hermes dump --show-keys

第二步：将输出保存为文件
hermes dump --show-keys > ~/hermes-diag-$(date +%Y%m%d).txt

第三步：检查文件内容
cat ~/hermes-diag-*.txt | head -n 20

该命令输出不含任何 API Key 明文（仅显示 api_key: [REDACTED]），但包含完整的环境变量快照、模型配置摘要、技能列表及 gateway 绑定地址。把此文件发给同事或社区时，对方能立刻判断是 Python 版本冲突、端口被占，还是模型 provider 配置错写成 openai 却填了 Anthropic 的 key。