授权失败时，需依次验证API Key有效性、Base URL一致性、OAuth令牌状态、SSL证书配置及缓存凭证：1. 用hermes config show检查key是否非空且未被环境变量覆盖；2. 确认base_url为https://dashscope.aliyuncs.com/compatible-mode/v1等正确地址；3. 若用OAuth，运行hermes auth login重获token；4. 内网自签名证书需打SSL补丁；5. 删除~/.hermes/auth/与cache/tokens/并重置配置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试启动 Hermes Agent，但系统提示授权失败或认证验证错误，则可能是由于 API Key 无效、环境变量覆盖配置、Base URL 不匹配或 OAuth 令牌过期所致。以下是解决此问题的步骤：
一、验证 API Key 的有效性与注入方式
API Key 是 Hermes Agent 向模型服务发起请求的身份凭证，若其为空、格式错误、权限不足或已失效，将直接触发授权拒绝响应。必须确保密钥正确写入配置且未被更高优先级来源覆盖。
1、执行 hermes config show 命令，检查输出中 model.api_key 字段是否显示为非空字符串，且值以 sk- 或对应平台前缀开头。
2、若字段显示为 from environment，运行 env | grep -i "api_key\|hermes_api" 确认是否存在拼写错误的环境变量（如 HERMES_APIKEY 缺少下划线）。
3、若使用百炼平台，登录 DashScope 控制台，进入 API-KEY 管理 页面，确认该 Key 状态为“启用”，且所属项目具有调用 qwen-turbo 或目标模型的权限。
4、临时绕过配置文件，直接在命令行中设置并测试：HERMES_API_KEY="sk-xxxxxxxx" hermes model list，观察是否仍报错。
二、检查 Base URL 与认证端点一致性
部分模型服务商要求 API Key 必须配合特定域名和路径才能完成签名验证，Base URL 错误会导致服务端无法识别凭据来源，返回 401 Unauthorized 而非 403 Forbidden。
1、打开 ~/.hermes/config.yaml，定位 model.base_url 字段，确认其协议为 https://，且完整包含服务商指定路径，例如百炼应为 https://dashscope.aliyuncs.com/compatible-mode/v1。
2、执行 curl 命令直连认证端点：curl -I -H "Authorization: Bearer sk-xxxxxxxx" https://dashscope.aliyuncs.com/compatible-mode/v1/models，观察响应头中是否含 HTTP/2 200 及 Content-Type: application/json。
3、若返回 401，检查 Key 是否被用于错误区域（如百炼国际站 Key 不能用于中国站接口），或 Base URL 中是否混入空格、中文字符、多余斜杠。
三、排查 OAuth 令牌过期或作用域缺失
当 Hermes Agent 配置为通过 OAuth 流程接入 Google Vertex AI、Microsoft Azure AI Studio 等平台时，长期有效的访问令牌可能已过期，或初始授权未勾选必要作用域（如 https://www.googleapis.com/auth/generative-language）。
1、检查配置中是否存在 auth.oauth_token 或 auth.refresh_token 字段，若存在且时间超过 60 分钟，需重新触发 OAuth 流程。
2、运行 hermes auth login --provider google（替换为实际 provider），按提示在浏览器中完成授权并回调至本地端口。
3、授权成功后，检查 ~/.hermes/auth/google.json 文件中 expires_in 字段是否大于 0，且 token_type 为 Bearer。
4、若仍失败，在 OAuth 授权页面手动勾选所有与 AI Platform 和 Generative Language API 相关的作用域选项后重试。
四、禁用 SSL 证书验证（仅限内网/自签名证书环境）
在飞书机器人、企业微信或私有化部署的模型网关环境中，若服务端使用自签名证书，Python 默认 HTTPS 客户端会因证书链不可信而中断 TLS 握手，导致授权请求在传输层即失败，错误信息常含 CERTIFICATE_VERIFY_FAILED。
1、在 ~/.hermes/hermes-agent/ 目录下创建 hermes_agent_ssl_patch.py 文件。
2、写入以下内容：import ssl; ssl._create_default_https_context = ssl._create_unverified_context。
3、修改 Hermes Agent 启动脚本，在首行添加：import sys; sys.path.insert(0, "/home/user/.hermes/hermes-agent"); import hermes_agent_ssl_patch（路径需替换为实际绝对路径）。
4、重启 Hermes Agent 并执行 hermes model test，确认是否跳过证书校验并成功收到响应。
五、清除缓存凭证与重置认证状态
Hermes Agent 在首次认证成功后会将令牌缓存至本地磁盘，若缓存文件损坏或版本不兼容，可能导致后续请求携带无效签名，表现为重复授权失败。
1、停止正在运行的 Hermes Agent 进程：hermes stop 或 killall hermes-agent。
2、删除全部认证相关缓存：rm -rf ~/.hermes/auth/ ~/.hermes/cache/tokens/。
3、清空当前 shell 会话中的所有 Hermes 相关环境变量：unset $(env | grep -i hermes | cut -d'=' -f1)。
4、重新执行交互式配置：hermes config init，全程不依赖已有缓存，从零重建凭证链。
