极可能是配置路径错误、环境变量覆盖、文件权限异常或参数格式不合规所致：需依次确认配置文件路径与权限、检查环境变量是否覆盖配置、验证YAML语法与必填字段、排查Windows编码问题、必要时强制重置配置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已完成Hermes Agent安装，但在执行hermes model或启动服务后无法正常调用模型、提示空响应或配置未生效，则极可能是配置路径错误、环境变量覆盖、文件权限异常或参数格式不合规所致。以下是系统性排查与修复步骤：
一、确认配置文件真实写入位置与权限
配置文件可能被写入非预期路径（如当前用户目录下而非全局配置目录），或因权限不足导致内容未保存成功，造成后续读取为空。
1、执行命令定位实际配置文件路径：hermes config path，记录输出的绝对路径（例如/home/user/.hermes/config.yaml）。
2、使用ls -l检查该路径是否存在且可读写：ls -l /home/user/.hermes/config.yaml，若提示“No such file”，说明配置未写入目标位置。
3、若文件存在但大小为0字节，或属主为root而当前用户无写权限，执行：sudo chown $USER:$USER /home/user/.hermes/config.yaml && chmod 644 /home/user/.hermes/config.yaml。
4、手动打开该文件，确认顶层是否包含model:区块，且缩进为两个空格（YAML对缩进敏感，禁止使用Tab）。
二、验证环境变量是否意外覆盖配置项
若系统中设置了HERMES_MODEL_PROVIDER、HERMES_API_KEY等环境变量，将优先于config.yaml中的设置，导致配置界面输入的内容被静默忽略。
1、在终端中运行：env | grep -i hermes，检查是否有相关变量输出。
2、若存在输出，临时清除该变量：unset HERMES_MODEL_PROVIDER HERMES_API_KEY HERMES_BASE_URL。
3、重新执行hermes model进行交互式配置，并在完成时立即运行hermes config show核对输出是否与输入一致。
4、若需长期使用环境变量方式配置，必须确保hermes config show输出中对应字段显示为from environment，否则说明变量名拼写错误或未生效。
三、检查配置文件语法与必填字段完整性
YAML格式错误（如冒号后缺少空格、引号不闭合、布尔值未小写）或遗漏关键字段（如api_key或base_url）会导致解析失败，服务启动时静默跳过模型初始化。
1、使用在线YAML校验器（如https://yamlchecker.com/）粘贴config.yaml全文，确认无Parse error提示。
统一LLM网关 - 一个API对接70+AI模型，使用单一API密钥即可调用GPT、Claude、Gemini、Qwen、Deepseek、Grok等主流模型。
2、确认model:区块下至少包含以下四行（顺序不限，缩进统一）：
provider: custom
base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxx
default: qwen-turbo
3、检查api_key值是否被单引号或双引号包裹——必须不加引号，否则会被识别为字符串字面量而非密钥值。
4、验证base_url末尾无多余斜杠，且协议头为https://（百炼兼容模式不支持http://或省略协议）。
四、排查Windows平台特有的路径与编码问题
Windows用户通过CMD/PowerShell执行配置命令时，可能因控制台编码（如GBK）与UTF-8配置文件冲突，导致中文注释或特殊字符破坏YAML结构，或路径中反斜杠被误解析。
1、关闭所有CMD/PowerShell窗口，改用Windows Terminal（启用UTF-8）或VS Code集成终端重新操作。
2、执行chcp 65001将当前控制台代码页切换为UTF-8。
3、删除现有config.yaml文件，改用hermes model交互式配置（避免手动编辑出错）。
4、配置完成后，用记事本另存为：选择“另存为”→“编码”下拉菜单选UTF-8（非UTF-8-BOM），文件名保持config.yaml，保存类型为“所有文件”。
五、强制重置配置并重建默认结构
当配置文件已损坏且难以定位具体错误时，可安全清除全部用户配置，触发Hermes Agent自动生成符合当前版本规范的最小可用模板。
1、执行命令备份原配置：mv ~/.hermes/config.yaml ~/.hermes/config.yaml.bak。
2、运行hermes config init，该命令将生成全新config.yaml，含标准server、model、mq等骨架区块。
3、再次执行hermes model，仅填写必要字段（provider、base_url、api_key、default），其余保持默认。
4、保存后立即测试：hermes chat "你好"，若返回模型响应则证明基础配置链路通畅。
