hermes-doctor

name	hermes-doctor
description	诊断与抢救 Hermes Agent (NousResearch) 故障 — 401/Authentication Fails、provider 切换后 key 没注入、credential_pool 缺条目、HERMES_HOME 被环境变量重定向、gateway lock、stale config、备份恢复。Windows 优先。覆盖 .env / auth.json / HKCU\Environment / config.yaml profile 四处残留点排查、hermes auth 子命令族(v2026.4.3+)、credential_pool 4 种 rotation 策略、已知 issues
version	1.1.0
license	MIT
homepage	https://github.com/dongsheng123132/hermes-doctor
repository	https://github.com/dongsheng123132/hermes-doctor
platforms	["windows","macos","linux"]
metadata	{"hermes":{"tags":["hermes","troubleshoot","auth","deepseek","ops","doctor","credential-pool"],"related_skills":[],"last_synced_with_upstream":"2026-04-30T00:00:00.000Z"}}

Hermes Doctor — 故障诊断与抢救流程

何时触发本 skill

任一信号即触发:

• HTTP 401: Authentication Fails(尤其是 your api key: ****xxx is invalid)
• Authorization: Bearer no-key-required 之类字面占位符出现在请求 header(用 request_dump 看)
• hermes setup 不弹 API key 输入步骤,只显示绿色 ✓
• /model 切换 provider 后立刻 401/404
• hermes doctor 报红/黄
• gateway already running 启动失败
• WAL 文件 > 100MB

不要等用户描述清楚 — 看到上面任一症状立即载入 references/auth-troubleshooting.md。

第一原则:先确认 HERMES_HOME 在哪

Windows 上最容易踩的坑:HERMES_HOME 可能被 HKCU\Environment 重定向到非默认位置(比如 C:\Users\<u>\AppData\Local\hermes),而不是 ~/.hermes。诊断和修复必须先确认真路径,否则你改的是无效文件:

echo "$HERMES_HOME"                              # shell 当前值
reg query "HKCU\Environment" /v HERMES_HOME      # 持久化值
hermes dump --redact | head -20                  # hermes 自己认的路径

三处不一致就以 hermes dump 输出的为准。Windows 上的常见场景:U-Hermes 等打包发行版会把 HERMES_HOME 写到 %LOCALAPPDATA%\hermes(即 C:\Users\<USER>\AppData\Local\hermes),让默认的 ~/.hermes 变成空壳。如果你只改 ~/.hermes 下的文件而 hermes 没反应,八成就是这种情况。

黄金 5 步排查

详见 templates/triage-checklist.md。摘要:

1. 定位真 HERMES_HOME(上一节)
2. 跑 hermes dump --redact — 看运行时 provider/key/active_profile/请求 URL/Authorization 的真实样子。这一步常常一眼定位问题。
3. 看最新 request_dump — <HERMES_HOME>/sessions/request_dump_*.json 里的 request.headers.Authorization 和 request.url 是不是符合预期。如果 Authorization 是 Bearer no-key-required 或 Bearer <字面单词>,说明 key 注入失败,不是 key 本身的问题。
4. 排查 4 处残留点(顺序很重要,从隐蔽到显眼):
   • HKCU\Environment 的 HERMES_HOME、*_API_KEY(reg query "HKCU\Environment")