HTTP 401 错误源于 API Key 配置缺失、错误或未正确加载，需依次检查 .env 文件密钥格式、config.yaml 中模型与密钥一致性、强制重载配置、验证 auth 登录状态，并启用 debug 日志定位具体失败环节。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在启动 Hermes Agent 时遇到 HTTP 401: Authentication failed 错误，这表明模型服务提供商拒绝了当前请求的身份认证，核心原因通常是 API Key 配置缺失、错误或未被正确加载。以下是解决此问题的步骤：
一、验证 API Key 是否已正确写入 .env 文件
该方法通过检查环境变量文件确认密钥是否以标准格式存在并可被 Hermes Agent 自动读取。Hermes 默认优先从项目根目录或用户主目录下的 .env 文件加载密钥，若该文件不存在或字段名不匹配，将直接触发 401。
1、执行命令定位 Hermes 配置路径：
hermes config show-path
2、进入输出路径（通常为 ~/.hermes/），检查是否存在 .env 文件：
ls -la ~/.hermes/.env
3、若文件存在，使用 cat 命令查看内容：
cat ~/.hermes/.env
4、确认其中包含与所用模型提供商严格匹配的变量名，例如：
DEEPSEEK_API_KEY=sk-xxx 或 OPENROUTER_API_KEY=sk-or-v1-xxx
5、若变量名拼写错误（如写成 DEEPSEEK_KEY 或 deepseek_api_key），请修正为全大写、下划线分隔的标准命名格式。
二、检查 config.yaml 中的模型配置与密钥来源一致性
该方法用于排查 YAML 配置中指定的模型标识与实际密钥注入方式之间是否冲突。当 config.yaml 显式声明某模型使用特定 provider（如 deepseek/custom/main），但对应密钥未通过环境变量或内嵌方式提供，Hermes 将无法构造合法请求头，从而返回 401。
1、打开 ~/.hermes/config.yaml 文件：
nano ~/.hermes/config.yaml
2、查找 llm: 节点下的默认模型设置，例如：
model: deepseek/custom/main
3、根据模型前缀（如 deepseek/）确定应使用的密钥变量名，对照官方文档确认标准前缀映射关系。
4、在同级节点下检查是否存在内嵌密钥配置，例如：
providers:
deepseek:
api_key: "sk-xxx"
5、若存在内嵌配置，请确保其值非空且格式正确；若不存在，则必须依赖外部 .env 文件提供对应变量。
三、强制重载模型配置并绕过初始化缓存
该方法适用于环境变量已正确设置但 Hermes 启动时未能及时解析的情况，尤其在 WSL2、Docker 容器或多次快速重启后常见。通过 CLI 指令可跳过初始配置缓存，强制重新绑定模型与密钥。
1、启动 Hermes 交互终端：
hermes
2、在提示符 > 后输入模型切换指令：
/model deepseek/custom/main
统一LLM网关 - 一个API对接70+AI模型，使用单一API密钥即可调用GPT、Claude、Gemini、Qwen、Deepseek、Grok等主流模型。
3、观察终端是否返回成功提示，例如：
[INFO] Model provider 'deepseek' reloaded with valid API key
4、退出交互模式：
Ctrl+D
5、重新运行网关服务：
hermes gateway start
四、使用 hermes auth register/login 确保账户凭据有效
该方法针对启用了身份认证中心（Auth Server）的部署场景。即使模型密钥正确，若 Hermes Agent 未完成本地账户登录或令牌过期，auxiliary_client 在调用后台任务时仍会因会话凭证无效而收到 401。
1、检查当前登录状态：
hermes auth status
2、若显示 Not logged in，执行注册（仅首次）：
hermes auth register --email your@email.com --password yourpass
3、执行登录：
hermes auth login
4、输入邮箱与密码后，确认返回 Login successful
5、再次启动网关并观察 auxiliary_client 日志：
hermes gateway logs
五、临时启用调试日志以定位具体失败环节
该方法通过提升日志级别暴露认证流程中的中间状态，帮助识别是密钥读取失败、HTTP 请求头未构造、还是远端服务返回明确拒绝。默认日志通常隐藏敏感字段，需显式开启调试模式。
1、在启动命令前添加环境变量：
HERMES_LOG_LEVEL=debug hermes gateway start
2、等待日志输出出现 [DEBUG] Loading API key for provider 'deepseek' 类似行
3、若该行缺失，说明密钥未被识别；若出现 [DEBUG] Using API key: sk-*** (masked)，则继续追踪后续 HTTP 请求日志
4、查找包含 Authorization: Bearer 的请求头输出，确认其值非空且格式合规
5、若请求头为空或为 Bearer null，则问题锁定在密钥加载阶段
