使用 Hermes Agent 时，绝大多数异常问题（模型调用失败、API 不生效、跨域失效、密钥不生效），根源都来自配置文件加载异常、参数覆盖错乱、环境配置不匹配。
很多新手遇到报错只会盲目重启服务，却不会查看、校验、追溯真实生效配置。本文系统化讲解 Hermes Agent 配置文件的查看命令、路径定位、内容解析、多配置优先级、故障排查，帮你彻底搞定配置类问题，精准定位问题根源。
一、前置认知：Hermes 两大核心配置文件
Hermes Agent 所有运行逻辑依赖两份核心配置文件，分工明确，缺一不可，这是看懂配置的基础：
1. config.yaml（主业务配置）
核心配置文件，存储模型服务商、默认模型、工具权限、技能配置、终端交互规则等核心业务参数，是日常修改最多的配置文件。
2. .env（环境变量配置）
全局环境配置，优先级高于 yaml 文件，存储API 开关、端口、跨域域名、鉴权密钥、全局环境变量，主要用于服务部署、API 网关配置。
3. 配置优先级（重点！）
临时命令参数 > .env 环境变量 > config.yaml 默认配置
这也是很多人改了配置不生效的核心原因：高优先级配置覆盖了低优先级配置。
二、新手必学：极简配置查看命令（开箱即用）
Hermes 提供原生 CLI 命令，无需手动找文件、打开编辑，一条命令即可查看完整生效配置。
1. 快速查看精简生效配置
hermes config该命令会只展示被修改、覆盖过的非默认配置，隐藏系统默认参数，界面简洁，适合快速核对自定义配置，比如自定义模型、服务商、工具开关等核心修改项。
2. 查看完整全量配置（排查问题首选）
hermes config show相比于精简模式，hermes config show会输出所有生效配置（默认值+自定义值），按技能、模型、网关、工具分类展示，是排查配置缺失、参数异常的核心命令。日常遇到诡异报错，优先执行该命令校验全量配置。
三、高阶实操：精准定位配置文件路径
很多场景需要手动打开配置文件编辑、备份、比对，首先要精准找到文件真实路径，无需逐层翻目录。
1. 查看主配置文件路径（config.yaml）
hermes config path执行后直接输出完整绝对路径，默认统一为：~/.hermes/config.yaml，适配 Windows、Mac、Linux 全平台。
2. 查看环境变量配置路径（.env）
hermes config env path快速定位 .env 文件位置，默认路径：~/.hermes/.env，专门用于修改 API 端口、鉴权、跨域等服务配置。
3. 直接打开配置文件编辑
# 直接打开 config.yaml
hermes config edit
# 直接打开 .env 环境配置
hermes config env edit系统会自动调用默认编辑器打开文件，无需复制路径、手动 cd 跳转，高效便捷。
四、精细化查看：单配置项精准查询
无需刷屏查看全部配置，支持精准提取单个配置参数，适合脚本校验、快速核对特定配置。
核心命令：hermes config get
# 查看当前默认模型
hermes config get model.default
# 查看当前模型服务商
hermes config get model.provider
# 查看工具权限配置
hermes config get tools.enable
# 查看技能配置
hermes config get skills.config优势：精准定位目标参数，输出干净无冗余，可直接用于自动化脚本、配置校验场景。
五、多配置文件管理：Profile 配置组查看
Hermes 支持多配置文件（Profile）切换，适配开发/测试/生产多环境隔离场景，很多开发者忽略该能力，导致环境配置混乱。
1. 查看所有配置文件列表
hermes profile show展示本地所有配置组、当前生效配置、配置状态、技能数量、网关绑定信息。
2. 查看指定配置文件详情
hermes profile show dev精准查看 dev 环境配置的模型、密钥、服务参数，实现多环境配置隔离管理。
六、配置校验与问题排查命令
查看配置后，需校验配置是否合法、是否加载成功、是否存在冲突，配套排查命令必不可少。
1. 全局环境配置体检
hermes doctor自动检测配置文件语法错误、密钥有效性、模型连通性、网关配置冲突，精准提示配置异常位置，新手排错神器。
2. 初始化重置异常配置
hermes setup当配置文件损坏、语法报错、加载失败时，执行该命令可重置基础配置，保留有效自定义参数，修复配置异常。
七、高频场景：配置查看实操组合拳
整理日常开发、调试、排错高频组合命令，直接复制套用。
场景1：快速核对当前运行配置
hermes config # 查看自定义修改配置
hermes config show # 查看全量生效配置场景2：配置修改不生效排查
hermes config get model.default # 核对目标参数
hermes doctor # 检测配置冲突/语法错误
hermes config path # 确认修改的是生效配置文件场景3：API服务配置核查
hermes config env path # 定位环境配置
hermes config env edit # 编辑API端口/密钥/跨域配置
hermes gateway status # 校验服务是否加载新配置场景4：多环境配置切换核查
hermes profile show # 查看所有配置环境
hermes profile show prod # 查看生产环境配置详情八、新手高频踩坑总结
- 分不清配置优先级：.env 环境变量会覆盖 config.yaml，修改yaml不生效时，优先检查.env配置。
- 混淆精简/全量查看：
hermes config只展示修改项，排查问题必须用hermes config show看全量配置。 - 改错配置文件：多环境下容易编辑错误配置组，用
hermes config path确认当前生效文件路径。 - 忽略配置语法错误：yaml 缩进错误会导致配置加载失败，用
hermes doctor一键检测。
九、全文总结
Hermes Agent 配置查看核心逻辑可以总结为 4 句话：
- 日常自查用 hermes config，简洁高效；
- 问题排查用 hermes config show，全量无遗漏；
- 定位文件用 config path / env path，精准直达；
- 异常排错用 hermes doctor，自动校验修复。
熟练掌握这套配置查看体系，能解决 90% 以上的 Hermes 启动、调用、服务异常问题，彻底告别盲目重启、瞎改配置的低效调试方式。
