config.yaml格式错误导致Hermes Agent启动失败，需依次验证YAML语法、嵌套层级、非法字符、字段完整性，并启用debug模式定位具体错误行。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在启动 Hermes Agent 时遇到 config.yaml: unmarshal error、invalid YAML syntax 或 failed to load config 等提示，则很可能是 config.yaml 文件存在格式错误。以下是排查此类问题的具体方法：
一、验证 YAML 基础语法合法性
YAML 对缩进、冒号、引号等符号极为敏感，任何不一致的空格或制表符都可能导致解析失败。该步骤用于快速定位语法硬伤。
1、使用在线 YAML 验证工具（如 yamllint.com）粘贴 config.yaml 全文，检查是否报出 expected <block end>、did not find expected key 等错误。
2、在终端中运行 yamllint ~/.hermes/config.yaml（若未安装，执行 pip install yamllint）。
3、确认所有键名后紧跟英文冒号与**单个空格**，例如 port: 8080，而非 port:8080 或 port : 8080。
4、检查是否混用 Tab 与空格缩进——必须全程使用空格，且同级元素缩进宽度一致。
二、检查嵌套结构层级错位
config.yaml 中 server、mq、executor 等顶级区块需严格对齐，子字段缩进需精确为 2 或 4 个空格，层级错位将导致字段被忽略或归属错误。
1、打开 config.yaml，确认 server:、mq:、executor: 等根节点顶格书写（行首无空格）。
2、检查 host: 和 port: 是否位于 server: 下方且缩进相同（推荐 2 空格）。
3、若配置了 Kafka，确认 brokers: 列表项以 - 开头，且每个地址前有**恰好 2 个空格**，例如：
- host1:9092。
4、检查布尔值是否全部小写，如 verify_ssl: false，禁止使用 False 或 FALSE。
三、识别非法字符与编码问题
中文全角标点、不可见 Unicode 字符（如零宽空格）、BOM 头等均会导致解析器崩溃，尤其在 Windows 编辑器中易引入。
1、用 file -i ~/.hermes/config.yaml 检查文件编码，预期输出应为 utf-8；若显示 utf-8-with-bom，需用 VS Code 或 vim 转为纯 UTF-8。
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
2、运行 cat -A ~/.hermes/config.yaml | grep '\^M\|@' 查找 DOS 行尾（^M）或异常控制字符。
3、删除所有中文引号（“”）、破折号（——）、省略号（…），替换为英文半角符号（""、-、...）。
4、对 API Key 等含特殊字符的字段，**必须用双引号包裹**，例如：api_key: "sk-xxx#2026@prod"。
四、比对官方配置模板校验字段完整性
缺失必需字段（如 server.host、mq.type）虽不总引发语法错误，但会触发运行时 panic，需结合文档确认字段存在性与位置。
1、从 GitHub 官方仓库获取最新 config.yaml 模板：
curl -s https://raw.githubusercontent.com/NousResearch/hermes-agent/main/config.example.yaml > /tmp/config.example.yaml。
2、使用 diff -u /tmp/config.example.yaml ~/.hermes/config.yaml 对比差异，重点关注 - （缺失）与 + （多余）行。
3、确认 model.default 和 model.provider 位于顶层，而非嵌套在其他块内。
4、检查 base_url 字段值是否以 https:// 开头，且末尾**无斜杠**（如 https://api.majiabin.com/v1 正确，https://api.majiabin.com/v1/ 错误）。
五、启用调试模式获取精准错误位置
Hermes Agent 内置详细解析日志，可直接暴露哪一行、哪一列发生解析中断，避免盲目排查。
1、执行 hermes --config ~/.hermes/config.yaml --log-level debug server start 启动服务。
2、观察终端输出中形如 yaml: line 42: did not find expected key 的提示，定位到具体行号。
3、用 sed -n '42p' ~/.hermes/config.yaml 提取第 42 行内容，检查该行及上一行缩进与冒号格式。
4、若提示 could not find expected ':'，重点检查该行是否遗漏冒号，或冒号后紧邻换行而无空格。
