API Key无效需依次检查：一、清除配置中前后空格；二、确认密钥未过期或被撤销；三、确保provider与密钥来源平台匹配；四、排查.env环境变量覆盖；五、用curl直连验证有效性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在启动或使用 Hermes Agent 时收到“API Key 无效”提示，则可能是由于密钥未正确加载、格式错误或与所选模型提供商不匹配。以下是解决此问题的步骤：
一、确认 API Key 已正确复制且无多余空格
API Key 在粘贴过程中常因误触空格键或换行符导致开头或结尾混入不可见字符，从而被解析为非法值。
1、打开终端，执行 hermes config show 查看当前生效的 API Key 显示内容。
2、若输出中 key 值两端存在空格（如 " sk-xxx "），说明存在前后空白字符。
3、运行 hermes config edit 进入配置文件编辑模式，手动删除 api_key 字段值两侧所有空格及换行符，确保其形如 api_key: sk-xxx（冒号后仅一个空格，无引号包裹）。
二、检查 API Key 是否过期或已被撤销
部分模型提供商（如 Anthropic、OpenRouter）会对 API Key 设置有效期或允许用户主动撤销，过期或撤销后的密钥将无法通过认证校验。
1、访问对应平台账户的 API 密钥管理页面（例如 OpenRouter 的 https://openrouter.ai/keys）。
2、查找当前使用的密钥条目，确认其状态是否为 Active，并核对 Expiration 时间是否晚于当前日期（2026年4月23日）。
3、若已过期或显示 Revoked，点击 Regenerate 生成新密钥，并立即复制新值替换本地配置中的旧值。
三、验证模型提供商与 API Key 是否匹配
Hermes Agent 要求所配置的 HERMES_MODEL_PROVIDER 环境变量或 config.yaml 中的 provider 字段必须与 API Key 所属平台严格一致，否则会触发认证拒绝。
1、执行 hermes config show | grep provider 获取当前 provider 名称（如 openai、anthropic、openrouter）。
2、比对 API Key 来源：OpenAI 密钥以 sk-... 开头；Anthropic 密钥以 sk-ant-api03-... 开头；OpenRouter 密钥以 sk-or-v1-... 开头。
3、若 provider 为 openai 但密钥实际来自 OpenRouter，则需修改配置：运行 hermes config set provider openrouter 并重新输入密钥。
四、手动编辑 .env 文件检查环境变量覆盖
若系统中设置了 HERMES_API_KEY 环境变量，它将优先于 config.yaml 中的配置项，且错误的环境变量值会导致静默失效。
1、执行 cat ~/.hermes/.env 查看是否存在 HERMES_API_KEY 行。
2、若存在且值为空、明显错误或与 config.yaml 不一致，使用文本编辑器打开该文件：nano ~/.hermes/.env。
3、定位到 HERMES_API_KEY= 行，将其整行删除，或修改为正确的密钥值（不加引号，无空格）。
4、保存后执行 source ~/.hermes/.env 使变更立即生效。
五、测试密钥是否可通过 curl 直接调用验证
绕过 Hermes Agent 框架，直接使用原始 HTTP 请求验证密钥有效性，可排除框架层干扰。
1、根据 provider 类型构造请求：对于 OpenAI，运行：curl https://api.openai.com/v1/models -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json"（将 sk-xxx 替换为实际密钥）。
2、若返回 JSON 格式的模型列表，说明密钥有效；若返回 {"error":{"message":"Incorrect API key provided","type":"invalid_request_error",...}}，则密钥无效或拼写错误。
3、若 curl 返回 401 或 403，且确认密钥无误，检查是否遗漏了必需的请求头（如 OpenRouter 需额外添加 -H "HTTP-Referer: https://hermes-agent.nousresearch.com"）。
