先判断错误发生在哪一层
API Key 问题通常不等于“密钥一定错了”。Hermes 可能没有读取到变量、读取了错误的 Profile，或者请求已经到达供应商但被权限、余额、模型名称或区域策略拒绝。排查时不要先重装，先确认错误边界。
第一步：确认当前运行的是哪个 Profile
命名 Profile 可能使用独立的配置目录。先确认启动命令和当前 Profile 一致，再检查对应目录中的配置文件是否存在。不要把 default Profile 的配置当成其他 Profile 的配置。
hermes profile list
printf '%s\n' "$HERMES_HOME"
如果命令没有列出预期 Profile，先处理 Profile 路径问题；如果 Profile 正常，再继续检查供应商配置。
第二步：确认变量存在，但不要打印密钥
可以只检查变量是否为空、长度是否合理，不能把完整密钥输出到终端、日志或聊天记录：
if [ -n "$MODEL_API_KEY" ]; then
echo "MODEL_API_KEY is set"
else
echo "MODEL_API_KEY is missing"
fi
变量名必须与 Hermes 当前配置和供应商要求完全一致。常见错误包括拼写差异、变量只写在交互式 Shell 中、后台服务没有继承环境变量，以及在错误的 Profile 中设置变量。
第三步：区分认证失败和模型参数失败
错误信息中如果出现 401 或 invalid api key，优先检查密钥来源、前后空格和账户权限；如果出现 404、model not found 或模型名称相关提示，重点检查模型 ID 和供应商端点；如果出现超时或连接错误，则应检查网络、代理和 DNS，而不是立即更换密钥。
第四步：用最小请求验证
先让 Hermes 执行一个不涉及 Skill、MCP 和复杂任务的最小请求。最小请求成功后，再逐项恢复工具和长任务，这样才能知道问题是在模型连接层还是工具层。
不建议的做法
- 把密钥直接写进
SOUL.md、Skill 或 Git 仓库； - 在排查时把完整环境变量复制到聊天窗口；
- 同时更换模型、供应商和 Profile，导致无法判断真正原因；
- 看到认证错误就反复运行安装脚本。
验收标准
排查结束后应能回答四个问题：当前 Profile 是什么、变量由哪里注入、请求到达了哪个端点、最小请求是否成功。若仍无法确定，应保留脱敏后的错误码和时间，而不是猜测密钥内容。