模型调用失败主因是API密钥未正确配置，需按场景选择.env文件、YAML配置、国内厂商适配、本地Ollama或密钥权限校验五种路径解决。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在启动Hermes Agent后遇到模型调用失败、API认证拒绝或“invalid API key”类报错，则极可能是模型密钥未正确注入至运行环境。以下是针对该问题的多种配置路径，覆盖主流部署场景与常见疏漏点：
一、通过.env文件注入OpenRouter密钥
此方式适用于本地开发及多数脚本化部署场景，Hermes Agent默认优先读取项目根目录下的.env文件，以环境变量形式传递密钥，避免硬编码风险。
1、访问OpenRouter密钥管理页面，登录账户后点击“Create new key”生成新密钥。
2、完整复制生成的密钥字符串（格式为sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx）。
3、在Hermes Agent项目根目录下创建或编辑.env文件，写入以下内容（注意等号两侧无空格）：
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
4、确保终端当前工作目录为项目根目录，执行hermes --version验证环境变量是否已加载；若仍报错，尝试重启终端或重新执行source ~/.bashrc（Linux/macOS）或RefreshEnv（PowerShell）。
二、通过YAML配置文件注入OpenRouter密钥
当容器化部署、权限受限或需多环境差异化配置时，可将密钥直接嵌入YAML配置文件，由Hermes Agent启动时解析加载，跳过系统级环境变量依赖。
1、定位Hermes Agent主配置文件，通常为config.yaml或agent_config.yaml，路径一般位于C:\Users\{用户名}\AppData\Local\hermes\（Windows）或~/.local/share/hermes/（Linux/macOS）。
2、在文件中找到llm:节点，在其下新增openrouter:子节，并填入密钥字段：
llm:
openrouter:
api_key: "sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
3、严格检查YAML缩进：必须使用空格（不可用Tab），api_key前为两个空格，且引号为英文双引号。
4、保存文件后，在终端执行hermes doctor命令，确认输出中显示OpenRouter client initialized；若提示解析错误，请核对冒号后空格及引号格式。
三、配置国内模型提供商密钥（以智谱GLM为例）
国内用户常因网络策略无法稳定访问OpenRouter，此时可切换至智谱AI等合规服务商。其密钥不通过Bearer Token传递，而是作为独立字段嵌入请求头，需在配置中明确指定provider类型与base_url。
1、前往智谱AI开放平台注册账号，进入“API Key管理”，创建新密钥并复制。
2、在config.yaml中修改model:段落，设置如下结构：
model:
default: glm-5.1
provider: zhipu
base_url: https://www.php.cn/link/4002628957f70084918b0d02535b3bcaapi/paas/v4/
api_key: "your_zhipu_api_key_here"
api_mode: chat_completions
3、特别注意base_url末尾必须包含/，否则请求将返回404；api_mode需设为chat_completions以匹配GLM接口规范。
4、执行hermes model list，确认输出中包含glm-5.1且状态为active；若显示unavailable，请检查网络连通性及密钥是否被平台限制IP。
四、启用本地Ollama模型服务（零密钥方案）
完全规避API密钥依赖的最简路径是接入本地Ollama服务，其通过HTTP直连localhost，无需认证，适合离线调试、隐私敏感场景或模型快速验证。
1、在终端运行ollama list，确认目标模型（如llama3、phi3）已存在；若为空，执行ollama pull llama3下载。
2、启动Ollama服务：ollama serve，默认监听http://localhost:11434；保持该进程持续运行。
3、在config.yaml中添加Ollama provider配置：
llm:
ollama:
model: llama3
base_url: http://localhost:11434
4、执行hermes model switch ollama/llama3，随后运行hermes chat发起测试对话；若返回响应且无认证错误，即表示本地模型链路已就绪。
五、校验密钥有效性与权限范围
即使密钥格式正确、配置路径无误，仍可能因服务商端权限限制导致调用失败。需主动验证密钥本身是否具备对应模型的调用权，而非仅依赖本地配置成功。
1、对OpenRouter密钥：访问https://openrouter.ai/docs#authentication，使用curl -H "Authorization: Bearer sk-or-v1-..." https://openrouter.ai/api/v1/models测试基础鉴权，返回200且含模型列表即有效。
2、对智谱密钥：调用https://www.php.cn/link/4002628957f70084918b0d02535b3bcaapi/paas/v4/models（需携带Authorization: ZhipuAI your_api_key头），返回JSON含glm-5.1即权限正常。
3、检查密钥控制台中的“可用模型”列表，确保所选模型（如z-ai/glm-5.1或meta-llama/llama-3.1-8b-instruct）处于启用状态；部分密钥默认禁用高成本模型，需手动开启。
4、若使用组织级密钥，确认当前账户所属组织未设置模型访问白名单，或已将目标模型加入许可列表。
