hermes agent配置异常时需依次检查主模型、环境变量、工具模块、消息网关和记忆系统五项：主模型需在config.yaml中正确配置model.default、provider、api_key与base_url，并通过hermes doctor验证；.env文件须存在且含有效api密钥；工具需用hermes tools enable启用并reload；网关配置文件需字段完整且hermes gateway status显示connected；memory.db须存在、可读写，并通过hermes memory stats确认状态正常。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已完成Hermes Agent的基础安装，但无法正常响应或功能异常，则很可能是关键配置项遗漏或设置错误。以下是新手入门阶段必须逐项核对的配置检查列表：
一、确认主模型已正确配置
主模型是Hermes执行所有推理任务的核心依赖，未配置将导致空响应或报错“no model available”。配置需同时满足模型标识、API密钥与基础URL三者匹配。
1、打开配置文件：~/.hermes/config.yaml（Linux/macOS）或 %USERPROFILE%\.hermes\config.yaml（Windows）
2、检查model.default字段是否非空，且格式为provider/model-id，例如openrouter/anthropic/claude-3.5-sonnet
3、确认model.provider下对应provider区块中已填写有效api_key和base_url（如使用一步API，base_url必须为https://yibuapi.com/v1）
4、在终端执行hermes doctor，观察输出中Model Provider Status是否显示✅ OK
二、验证环境变量文件完整性
.env文件用于隔离敏感凭证，若缺失或路径错误，会导致API密钥无法加载，进而触发认证失败。
1、检查文件是否存在：~/.hermes/.env（Linux/macOS）或 %USERPROFILE%\.hermes\.env（Windows）
2、用文本编辑器打开该文件，确认至少包含一行有效密钥定义，例如OPENROUTER_API_KEY=sk-or-xxxxxxxx或YIBU_API_KEY=sk-yb-xxxxxxxx
3、确保无多余空格、中文字符或注释符号（#）出现在密钥值前，且每行仅含一个键值对
4、重启Hermes进程使新.env生效，避免缓存旧环境变量
三、检查工具模块启用状态
内置工具（如Shell执行、文件读写、网络请求）默认处于禁用状态，需显式启用才能调用，否则相关指令将被忽略或返回拒绝提示。
1、运行命令：hermes tools list，查看各工具当前状态是否为enabled
2、对需要使用的工具逐个启用，例如启用Shell工具：hermes tools enable shell
3、若使用自定义工具路径，确认tools_dir在config.yaml中指向有效目录，且目录内含合法.py文件
4、执行hermes tools reload强制刷新工具注册表
四、校验消息网关连接参数
当通过Telegram、Discord或微信等外部平台接入时，网关配置错误将导致消息无法收发或机器人离线。
1、检查网关配置文件是否存在：~/.hermes/gateways/目录下应有对应平台的JSON配置文件（如telegram.json）
2、打开该JSON文件，确认bot_token（Telegram）、app_id与app_secret（飞书）等字段值非空且格式正确
3、对于WebSocket类网关（如飞书），确认connection_mode设为websocket，且source字段值为feishu或lark
4、运行hermes gateway status，观察输出中Connection State是否为connected
五、排查记忆系统初始化异常
Hermes依赖本地SQLite数据库存储记忆，若数据库损坏或权限不足，将导致上下文丢失、技能无法持久化等问题。
1、定位记忆数据库路径：~/.hermes/memory.db（Linux/macOS）或 %USERPROFILE%\.hermes\memory.db（Windows）
2、确认该文件存在且大小不为0字节；若不存在，执行hermes memory init重建
3、检查文件权限：当前用户需具备读写权限，Windows下尤其注意是否被杀毒软件锁定
4、运行hermes memory stats，验证total_conversations与skills_count是否为合理正整数
