Hermes Agent 模型配置失败，最容易被误判成“模型名写错”。实际排查时要先拆成三块：provider 是否选对，API key 是否属于这个服务商，endpoint 是否真的能访问。模型名正确但接口地址错了，照样会报错。
先判断你用的是云端还是本地模型
如果你接 OpenAI、OpenRouter、Nous Portal 这类云端服务，重点检查 API key、账户额度、模型名和服务商兼容格式。如果你接 Ollama、vLLM、llama.cpp 这类本地服务，重点检查本地服务是否启动、端口是否可访问、是否支持工具调用。
最简单的判断方法：云端模型通常需要外网和 key；本地模型通常有 localhost、端口号或内网地址。两类配置不要混着写。
provider 和 endpoint 不要错配
provider 可以理解为“按谁的接口规则发请求”，endpoint 是“请求发到哪里”。如果 provider 写 OpenAI，但 endpoint 指向一个不完整兼容 OpenAI 的本地服务，聊天可能能跑，工具调用却失败。反过来，如果 endpoint 还是默认地址，但 key 是 OpenRouter 的，也可能鉴权失败。
排查时先固定一个最小组合：一个 provider、一个模型、一个 key、一个 endpoint。跑通后再配置 fallback、key 池或多个模型。
常见错误怎么处理
提示 401 或 unauthorized，优先换 key 或确认 key 没有复制空格。提示 404 或 model not found，说明模型名、路由或服务商不匹配。提示 429，多半是限流、余额不足或请求太频繁。提示 connection refused，通常是本地服务没启动或端口写错。
如果接本地模型，先用最简单的 curl 或本地前端确认模型服务能回答，再让 Hermes Agent 接入。不要在模型服务还没跑通时反复改 Hermes Agent 配置。
工具调用失败要额外看能力
代码代理不只是聊天，它还需要工具调用能力。某些模型可以普通对话，但不稳定支持 tool calling，表现就是它一直解释却不执行工具，或者工具参数格式乱。遇到这种情况，优先换一个明确支持工具调用的模型，再排查 Hermes Agent。
稳定配置的原则是：先选一个可靠模型跑通基础能力，再逐步加长上下文、本地模型、路由网关和多 key。一次加太多变量，最难定位问题。
