执行hermes命令无响应、模型不生效或提示“未配置模型”，需依次排查path未加载、配置文件路径/权限异常、yaml语法错误、网络/api密钥问题及模型索引服务连通性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您刚安装完Hermes Agent，执行命令却无响应、配置后模型不生效、或对话时提示“未配置模型”，很可能是基础环境或配置流程中存在隐性断点。以下是针对新手高频卡点的逐项排查与应对方案：
一、命令行输入 hermes 提示 command not found
该问题本质是系统未识别hermes可执行文件路径，通常因Shell环境未加载安装脚本写入的PATH变量所致，而非安装失败。
1、关闭当前终端窗口，重新打开一个全新终端实例。
2、在新终端中执行：source ~/.bashrc（若使用zsh则执行：source ~/.zshrc）。
3、运行echo $PATH，确认输出中包含类似/home/username/.local/bin的路径（Linux/macOS默认安装位置）。
4、再次输入hermes version，验证是否返回版本号。
二、hermes model 配置完成后，hermes chat 仍报错“no model configured”
配置内容未落盘至预期路径，或被高优先级环境变量覆盖，导致运行时读取为空配置。
1、执行hermes config path，获取实际配置文件绝对路径（如/home/user/.hermes/config.yaml）。
2、运行ls -l /home/user/.hermes/config.yaml，检查文件是否存在且大小非零。
3、若文件存在但属主为root，执行：sudo chown $USER:$USER /home/user/.hermes/config.yaml。
4、运行env | grep -i hermes，若输出任何HERMES_*变量，立即执行：unset HERMES_MODEL_PROVIDER HERMES_API_KEY HERMES_BASE_URL。
三、配置向导中完成输入，但 hermes config show 显示字段为空或为 null
YAML语法错误会导致解析器跳过整个model区块，常见于缩进不一致、冒号后缺空格、布尔值未小写等低级但致命的格式问题。
1、用文本编辑器打开/home/user/.hermes/config.yaml，确认model:下所有子字段均使用两个空格缩进，严禁使用Tab键。
2、检查每一行末尾无不可见控制字符，尤其api_key、base_url值必须用双引号包裹（如api_key: "sk-xxx"）。
3、访问https://yamlchecker.com/，粘贴config.yaml全文，确认返回“Valid YAML”。
4、手动补全model区块必需字段：model、provider、api_key、base_url（部分provider如OpenRouter可省略base_url，但必须显式声明）。
四、hermes doctor 检测通过，但 hermes chat -q “Hello” 无响应或超时
网络连接或API密钥权限异常导致请求无法抵达模型服务端，本地进程仍在运行但收不到有效响应。
1、在终端中直接执行：curl -v https://api.openrouter.ai/v1/models（以OpenRouter为例），观察是否返回HTTP 200及JSON列表。
2、若返回Connection refused或timeout，检查系统代理设置：echo $HTTPS_PROXY，如有输出且非预期，执行：unset HTTPS_PROXY HTTP_PROXY。
3、若curl正常但hermes仍超时，临时启用调试日志：hermes chat -q "Hello" --verbose，定位阻塞在request send还是response parse阶段。
4、确认API Key在对应平台控制台中处于启用状态，且未超出调用配额或触发风控拦截。
五、配置界面选择Quick Setup后，模型列表为空或仅显示“None”
配置向导依赖在线模型索引服务，若本地DNS解析失败或目标服务域名被临时屏蔽，将无法拉取可用模型清单。
1、执行：ping api.openrouter.ai（或其他所选provider域名），确认基础连通性。
2、若ping不通但网页可访问，尝试切换DNS：编辑/etc/resolv.conf，将nameserver改为8.8.8.8或114.114.114.114。
3、若使用国内网络，Quick Setup默认可能指向境外服务；改用手动配置模式，直接输入阿里云百炼、Kimi或DeepSeek的国内可用endpoint与Key。
4、运行hermes model --list-providers，核对输出中是否包含已知可用provider名称（如deepseek、kimi、bailian），若缺失则说明provider插件未正确加载。
