模型配置失败时需按五步系统修复：一、运行hermes model执行交互式向导强制写入；二、检查config.yaml中model区块字段完整性与yaml语法；三、清除干扰环境变量；四、用hermes config reload和debug日志验证加载；五、应急时手动写入标准model区块。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已完成Hermes Agent安装，但在执行hermes model或启动服务后模型列表为空、未显示已配置的模型、或提示“no model available”，则极可能是模型参数未写入配置文件、环境变量覆盖、YAML语法错误或模型区块缺失所致。以下是系统性修复步骤：
一、手动执行模型配置向导并强制写入
该步骤绕过自动检测逻辑，直接触发交互式模型绑定流程，确保model区块被显式写入config.yaml且不被跳过。
1、在终端中输入命令：hermes model 并回车执行。
2、当出现模型提供商列表时，使用方向键选择Custom endpoint (OpenAI compatible)。
3、在Base URL输入框中粘贴完整地址，必须以https://开头、末尾无斜杠、不含空格，例如：https://dashscope.aliyuncs.com/compatible-mode/v1。
4、在API Key输入框中粘贴密钥，格式必须为sk-开头的32位以上字符串，且不可包含引号或换行。
5、在Model Name输入框中填写具体模型标识，如qwen-turbo、qwen-plus、glm-4-flash等，不可留空。
6、全部确认后，等待终端输出Model successfully configured，表示模型已注册并写入配置文件。
二、检查并修正配置文件中的model区块结构
该步骤验证config.yaml中model层级是否符合Hermes Agent解析要求，避免因字段缺失、缩进错误或值类型异常导致模型被忽略。
1、执行命令定位配置路径：hermes config path，记录输出路径（如/home/user/.hermes/config.yaml）。
2、用文本编辑器打开该文件，确认顶层存在model:区块，且其下至少包含provider、base_url、api_key、default四个字段。
3、检查每个字段的缩进是否统一为两个空格，严禁使用Tab字符。
4、确认base_url和api_key值均被双引号包裹，例如："https://api.yibuapi.com/v1"、"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"。
5、确认default字段值为字符串类型，不可为null、true/false或数字，例如：default: "qwen-turbo"。
三、清除环境变量干扰并重载配置
该步骤防止HERMES_MODEL_PROVIDER、HERMES_API_KEY等环境变量优先于配置文件生效，造成界面输入内容被静默覆盖。
1、运行命令检查当前生效的Hermes相关变量：env | grep -i "hermes\|api\|model"。
2、若输出包含HERMES_MODEL_PROVIDER、HERMES_API_KEY、HERMES_BASE_URL等任意一项，立即执行unset命令清除：unset HERMES_MODEL_PROVIDER HERMES_API_KEY HERMES_BASE_URL。
3、重新运行hermes config show，确认model.provider、model.base_url等字段显示为from config而非from environment。
4、若仍显示from environment，检查~/.bashrc、~/.zshrc或~/.hermes/.env中是否存在export语句，将其注释或删除后执行source ~/.zshrc（或对应shell配置文件）。
四、验证模型配置是否被正确加载
该步骤通过底层命令直连配置解析器，排除CLI缓存或服务进程未重启导致的显示延迟问题。
1、执行命令强制重读配置：hermes config reload。
2、运行调试模式查看初始化日志：hermes --log-level DEBUG model list 2>&1 | grep -i "loaded\|model\|config"。
3、在输出中查找形如“Loaded model config from /home/user/.hermes/config.yaml”和“Registered model: qwen-turbo”的日志行，若缺失前者，说明配置路径错误；若缺失后者，说明model区块未通过语法校验。
4、若日志中出现“YAML parse error”或“missing required field”，返回第二步修正语法与字段完整性。
五、手动注入模型参数至配置文件（应急方式）
该步骤适用于向导失败、文件权限受限或需批量部署场景，通过直接编辑YAML完成模型注册，跳过交互流程。
1、确保~/.hermes目录存在且可写：mkdir -p ~/.hermes && chmod 755 ~/.hermes。
2、创建或清空config.yaml：> ~/.hermes/config.yaml。
3、向文件写入标准model区块，严格按以下格式（注意空格与引号）：
model:
provider: "custom"
base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
default: "qwen-turbo"
4、保存后执行：hermes config show，确认输出中model部分完整显示且无报错提示。
5、最后运行：hermes chat -q "测试"，验证模型是否返回有效响应。
