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。诊断和修复必须先确认真路径,否则你改的是无效文件:

bash

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")
   • shell 进程环境( echo "$DEEPSEEK_API_KEY" 等)
   • <HERMES_HOME>/auth.json 的 credential_pool.<provider> 数组( 最容易缺)
   • <HERMES_HOME>/.env 和 <HERMES_HOME>/config.yaml(顶层 model.api_key + model_profiles.*.api_key)

5. 备份后修复(详见 references/auth-troubleshooting.md):

   • 永远先 cp <file> <file>.broken-$(date +%Y%m%d-%H%M%S)
   • 修完跑 hermes doctor 验证,启动 hermes 发 ping

常见症状速查表#

症状大概率根因跳到your api key: ****ired is invalidkey 是字面 expired 或 no-key-required 占位符,没注入到 headerreferences/auth-troubleshooting.mdAuthorization: Bearer no-key-requiredcredential_pool 缺该 provider 条目references/auth-troubleshooting.md §"占位符注入"hermes setup 不弹 key 输入issue #16394:.env 里有该 KEY 行就静默跳过references/auth-troubleshooting.md §"setup 静默跳过"/model 切完 404issue #3685:api_mode 残留references/provider-switch.mdgateway already runninglock 文件残留references/doctor-and-dump.md §gatewayWAL 巨大response_store/state 数据库未 checkpointhermes doctor --fix跨机迁移后全报错API key 没在新机重新填,base_url 错references/backup-and-migrate.md

危险动作清单(执行前必须明确得到用户授权)#

只要你打算做下面任一操作,先把动作和影响告诉用户、等他点头,再做:

• 删 <HERMES_HOME>/.env 任一行
• 改 <HERMES_HOME>/auth.json 的 credential_pool(可能会让另一些 provider 失联)
• 删 HKCU\Environment 的环境变量(影响所有应用,不只 hermes)
• 跑 hermes doctor --fix(会自动改 config 和 symlink)
• 删 sessions/ 或 state.db(无法恢复历史)
• 重新装 hermes-agent(venv 重建)

何时升级到人工#

hermes dump 显示运行时 key 与 4 处残留点都对不上 → venv 损坏的可能性 > 90%,建议:

1. 备份整个 HERMES_HOME 到 zip
2. 卸载并重装 hermes-agent ( pipx reinstall hermes-agent 或对应安装方式)
3. 重新跑 hermes setup
4. 把备份的 sessions/ memories/ skills/ 复制回新 HERMES_HOME

排查时优先翻这些地方#

• 真 HERMES_HOME(用 hermes dump --redact 或 reg query "HKCU\Environment" /v HERMES_HOME 确认)
• Hermes Python 源码 — 诊断时直接读最准:
  • 标准 pip 安装: <venv>/Lib/site-packages/hermes_cli/(Win)或 <venv>/lib/python*/site-packages/hermes_cli/
  • 打包发行版(如 U-Hermes): <install-root>/hermes-agent/hermes_cli/
  • 关键文件: auth.py(provider 解析、PROVIDER_REGISTRY、 _resolve_api_key_provider_secret)、 doctor.py( run_doctor)、 setup.py(setup wizard)、 env_loader.py、 runtime_provider.py
• Hermes CLI 二进制:venv 的 Scripts/hermes.exe(Win)或 bin/hermes(Mac/Linux)

修复手段优先级#

故障定位后,优先用安全程度高的手段:

1. hermes auth 子命令(v2026.4.3+,推荐) — hermes auth add/remove/list/reset,见 references/credential-pool-and-rotation.md。先 hermes auth --help 看你装的版本支不支持
2. hermes doctor --fix — 修 stale config / WAL / symlink,不动 key
3. 手工 edit .env + auth.json — hermes auth 不可用或版本太旧时(参 references/auth-troubleshooting.md)。 关键:目前主流版本(0.10.x 及之前)的 _resolve_api_key_provider_secret() 只读 env,不读 credential_pool(issue #15914),所以 .env 和 auth.json 通常需要 双写 才稳定
4. hermes setup — 重跑全量 wizard,但 issue #16394 让它在 .env 已有 KEY 行时静默跳过,所以先删 .env 那行再跑
5. 重装 venv — 升级到人工

详细资料#

• references/auth-troubleshooting.md — 401/key 注入失败/setup 静默跳过的全套排查
• references/credential-pool-and-rotation.md — hermes auth 子命令、4 种 rotation 策略、池子坑(#15914/#5561/#6907/#7863)
• references/fallback-and-rate-limit.md — fallback_providers 链、429 cooldown、模型路由解析链(#15914/#16677)
• references/doctor-and-dump.md — hermes doctor 检查项 + hermes dump 用法
• references/config-and-paths.md — HERMES_HOME 解析、 <home>/ 下每个文件作用
• references/provider-switch.md — /model 切换、api_mode 陷阱、profile 配置
• references/backup-and-migrate.md — 备份恢复 HERMES_HOME,跨机迁移
• templates/triage-checklist.md — 出问题时按这张表逐条排
• assets/known-issues.json — 16 条已知 GitHub issues 结构化清单 + 6 个相关 release 摘要