API Key 配置错误是 Hermes Agent 启动失败或认证失败的主因，需依次验证变量名匹配、重载模型配置、运行 setup 向导、排查网络拦截、确认 Key 在服务商平台有效且权限正确。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试启动 Hermes Agent，但服务立即报错退出或日志中反复出现认证失败提示，则很可能是 API Key 配置错误所致。以下是解决此问题的步骤：
一、验证 .env 文件中 Key 变量名与 config.yaml 模型标识是否匹配
Hermes Agent 依赖环境变量名与配置文件中模型路径严格对应，若变量名拼写错误或缺失，将导致模型初始化失败。
1、打开配置文件 ~/.hermes/config.yaml，定位 model.default 字段，记录其值（例如 openai/gpt-4o 或 anthropic/claude-3-5-sonnet）。
2、打开环境文件 ~/.hermes/.env，检查是否存在与该模型提供商完全一致的大写变量名，例如 OPENAI_API_KEY 或 ANTHROPIC_API_KEY。
3、确认变量值不为空且无多余空格，API Key 字符串必须紧贴等号右侧，例如 OPENAI_API_KEY=sk-prod-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。
二、使用交互命令强制重载模型配置
该方法可绕过启动时环境变量加载异常，直接在运行时注入模型参数，适用于 Windows/WSL2 等环境变量加载不稳定场景。
1、启动 Hermes Agent 交互终端：hermes shell。
2、在提示符下输入模型切换指令：/model openai/gpt-4o（请将 openai/gpt-4o 替换为实际使用的模型路径）。
3、执行后观察终端是否返回 Model reloaded successfully 提示。
4、输入 /quit 退出交互模式，再运行 hermes start 启动服务。
三、重新运行 setup 向导并交互式录入 Key
setup 命令会自动校验模型可用性，并引导用户逐项输入有效凭证，避免手动编辑配置文件时的格式或命名疏漏。
1、在终端中执行：hermes setup。
统一LLM网关 - 一个API对接70+AI模型，使用单一API密钥即可调用GPT、Claude、Gemini、Qwen、Deepseek、Grok等主流模型。
2、当提示选择默认模型时，输入对应编号（如 1 代表 OpenAI）。
3、当提示输入 API Key 时，粘贴完整密钥字符串，注意不要包含引号或换行符。
4、向导完成时将自动生成合规的 config.yaml 和 .env 文件，并覆盖旧配置。
四、检查 Key 是否被防火墙或代理拦截
部分企业网络或本地代理会主动过滤含 “api_key”、“sk-” 等特征的 HTTP 请求头，导致认证请求未到达 LLM 服务商即被丢弃。
1、临时关闭系统代理设置，或在终端中执行：unset HTTP_PROXY HTTPS_PROXY。
2、运行 hermes logs 查看实时日志，确认错误是否从 AuthenticationError: Invalid API key 变为 Connection refused 或超时类错误。
3、若错误类型改变，说明原问题确由网络策略干扰引起，需联系网络管理员放行目标域名（如 api.openai.com）及请求头字段。
五、验证 Key 在原始服务商平台是否有效且权限正确
Key 本身可能已过期、被撤销，或所属账户未启用对应模型访问权限，此类问题无法通过本地配置修复。
1、登录对应服务商控制台（如 OpenAI Platform、Anthropic Console），进入 API Keys 页面。
2、确认该 Key 状态为 Active，且创建时间未超过 90 天（部分服务商对免费 Key 设有效期）。
3、检查 Key 所属组织是否已开通所用模型（例如 gpt-4o 需单独申请访问权限）。
4、在控制台使用该 Key 直接调用一次测试接口（如 OpenAI 的 /models 端点），确认返回 HTTP 200 及有效 JSON 响应。
