配置未生效需依次排查：一、确认~/.hermes/config.yaml和.env文件存在且路径正确；二、校验yaml语法，禁用tab、冒号后加空格、字符串加引号；三、执行source ~/.hermes/.env并验证环境变量是否载入；四、检查model区块中default、provider、base_url、api_key四项齐全且url协议匹配；五、启用hermes_log_level=debug查看日志是否显示loaded config from。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已完成Hermes Agent安装但配置始终无法生效，可能是由于配置文件路径错误、格式语法不合规、环境变量未加载或模型参数缺失所致。以下是针对性的排查步骤：
一、确认配置文件存在性与路径正确性
Hermes Agent在启动时仅读取预设路径下的config.yaml和.env文件；若文件不存在、路径偏差或被重命名，将导致配置完全不生效，系统回退至默认参数。
1、在Linux/macOS终端中执行ls -l ~/.hermes/config.yaml ~/.hermes/.env，确认两个文件均存在且非空。
2、在Windows系统中检查路径是否为C:\Users\用户名\AppData\Local\hermes\config.yaml与.env，注意AppData为隐藏文件夹，需在文件资源管理器地址栏直接粘贴路径访问。
3、若文件缺失，运行hermesagent init命令生成标准模板；若提示command not found，请先验证hermesdoctor check是否通过。
二、校验YAML语法与缩进规范
YAML对空格敏感，错误缩进、制表符混用或冒号后缺少空格会导致解析失败，此时Hermes Agent静默忽略整个配置段，不报错亦不生效。
1、将config.yaml内容复制至在线YAML校验工具（如yamllint.com），确认无Parse error或Incorrect indentation提示。
2、检查model层级下各字段是否严格使用空格缩进（禁止Tab），例如provider:与base_url:必须对齐，且冒号后必须保留一个空格。
3、验证字符串值是否包裹引号：含斜杠、下划线或特殊字符的api_key和base_url必须用双引号包围，如"https://api.majiabin.com/v1"。
三、验证环境变量加载状态
.env文件中的变量需被shell会话识别并注入进程环境，若未正确加载，则config.yaml中引用${API_KEY}等占位符的位置将为空，引发认证失败。
1、在终端中执行cat ~/.hermes/.env，确认内容为纯键值对格式，每行形如API_KEY=sk-xxx，无多余空格或注释符号#。
2、执行source ~/.hermes/.env && env | grep API_KEY（Linux/macOS）或Get-ChildItem Env: | Where-Object Name -eq 'API_KEY'（PowerShell），确认变量已载入当前会话。
3、若未显示，需在shell配置文件（如~/.bashrc或~/.zshrc）末尾添加source ~/.hermes/.env，再执行source ~/.bashrc重载。
四、检查模型参数完整性与协议兼容性
主模型配置中任意一项关键字段缺失（如provider、base_url、api_key）或协议版本不匹配（如v1接口误配v0路径），均会导致初始化中断，日志中仅出现Failed to load model provider。
1、打开config.yaml，定位model:区块，确认以下四字段全部存在且非空：default、provider、base_url、api_key。
2、比对所填base_url与目标服务商文档一致，例如OpenAI兼容接口须以/v1结尾，Majiabin接口须为https://api.majiabin.com/v1。
3、若使用自建模型服务，确认其响应头包含Content-Type: application/json，且返回结构符合OpenAI-style chat completions格式。
五、启用调试日志定位隐性配置错误
部分配置问题不会触发显式报错，但会在初始化阶段跳过模块加载，仅通过DEBUG级日志暴露线索，例如Skipping tool web_tools: missing required env WEB_TOOLS_DEBUG。
1、在启动前设置环境变量：export HERMES_LOG_LEVEL=DEBUG（Linux/macOS）或$env:HERMES_LOG_LEVEL="DEBUG"（PowerShell）。
2、执行hermesagent start --log-level debug，观察控制台输出中是否出现Loaded config from及后续model provider initialized字样。
3、若日志首行即为Using default configuration，表明config.yaml未被读取，应立即返回步骤一核查路径与权限。
