hermes doctor 诊断指南：读懂检查结果并安全修复

先运行基础诊断

`hermes doctor` 汇总 Hermes 版本、发布日期、Git 提交和检测到的安装方式，并检查配置与依赖。它不会默认修改你的环境。

hermes doctor
hermes version
hermes status

什么时候使用 --fix

确认输出中的修复项后再运行 `--fix`。自动修复适合缺失目录、可恢复配置和部分依赖问题，但不会代替你完成 Provider 凭据或系统权限决策。

hermes doctor --fix

先保存你手工修改过的 config.yaml 和 Skills。涉及凭据、网络代理或系统服务时，应按诊断提示人工处理。

Provider 与认证问题

如果诊断报告 API key 缺失、Provider 未知或 OAuth 失效，使用完整模型向导重新认证。

hermes model
hermes setup --portal
hermes portal info

• 不要在聊天内用 /model 添加新 Provider。
• 自定义端点需同时核对 base URL、模型名与上下文长度。
• 修改 Provider 后先跑一个纯文本请求，再启用复杂工具。

运行时和 PATH 问题

命令找不到或 ModuleNotFoundError 常见于调用了仓库源码入口，而不是安装器生成的虚拟环境启动器。重新打开终端并确认 PATH 指向 Hermes 安装目录。

where.exe hermes  # Windows
which hermes       # Linux / macOS / WSL2
hermes --version

Gateway 无法启动

先检查状态，再重新运行平台配置。令牌、allowlist、systemd/launchd 服务状态是最常见原因。

hermes gateway status
hermes gateway setup
hermes gateway run

WSL 中优先用 gateway run；原生 Windows、Linux systemd 与 macOS launchd 的服务行为不同。

提交问题前收集信息

报告问题时至少附操作系统、Python、Hermes 版本和完整错误。分享日志前检查是否已脱敏。

python --version
hermes version
hermes doctor