安装成功需用hermesdoctor五层验证：一查命令可用性，二做基础环境自检，三启详细日志排查隐性异常，四测端口连通性，五校配置文件语法与完整性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
装完Hermes Agent v0.19.1后，光看终端没报错不等于安装成功——很多用户执行hermes --version能出版本号，但后续hermes chat卡死、hermes model无响应、甚至hermes setup直接退出，根本原因是核心组件未就绪或配置未激活。必须用官方诊断工具hermesdoctor做五层递进式验证，缺一不可。
确认hermesdoctor命令是否可用
hermesdoctor是Hermes Agent官方内置的诊断工具，集成在v0.19.1安装包中。若该命令无法调用，说明安装脚本未正确写入PATH或二进制文件损坏。
打开终端（Linux/macOS）或管理员PowerShell（Windows），输入：
hermesdoctor --version
看到类似hermesdoctor 1.2.0的输出即通过；若提示command not found或'hermesdoctor' is not recognized，请立即检查~/.hermes/bin（macOS/Linux）或%USERPROFILE%\AppData\Local\hermes\bin（Windows）是否存在可执行文件，并手动将其加入PATH。
执行基础环境自检
这一步扫描Python运行时、必需模块（如pydantic【必须为v2.8+】）、配置文件~/.hermes/config.yaml是否存在，以及默认端口8080是否被占用。
在终端中执行：
hermesdoctor check
等待5–15秒，观察输出中的标记：所有条目显示[PASS]才表示基础环境就绪；任一[FAIL]项后会附带修复指引，例如[FAIL] Python version: 3.10.12 → requires >=3.11，此时必须升级Python而非跳过。
启用详细日志模式排查隐性异常
当基础检查全绿但hermes start仍失败时，问题往往藏在模块导入链或配置解析阶段，普通模式不会暴露。
运行：
hermesdoctor check --verbose
统一LLM网关 - 一个API对接70+AI模型，使用单一API密钥即可调用GPT、Claude、Gemini、Qwen、Deepseek、Grok等主流模型。
逐行查看控制台输出，重点捕捉以ERROR开头的行。若出现Failed to import module 'hermesagent.core'，说明Python环境隔离冲突——你很可能在conda虚拟环境中执行了全局安装，或pip install hermes-agent覆盖了官方一键脚本安装的版本，【此时必须卸载pip版本并重跑curl安装脚本】。
验证服务端口连通性
Hermes Agent默认监听本地TCP端口8080，但端口可能被Docker、VS Code Remote Server或其他AI服务抢占，仅靠netstat -an | grep 8080不够，需模拟真实服务探测。
先确保已尝试启动服务：
hermes start
再执行：
hermesdoctor check --port 8080
若返回Port 8080 is unreachable，不要立刻改端口——先执行lsof -i :8080（macOS/Linux）或netstat -ano | findstr :8080（Windows）查PID，再用kill -9 [PID]或任务管理器结束对应进程。强行换端口会导致后续hermes chat连接失败。
校验配置文件语法与完整性
方法一：快速语法检测
hermesdoctor check --config
方法二：深度完整性校验（推荐）
hermesdoctor check --config --verbose
该命令会加载~/.hermes/config.yaml，逐字段验证provider类型、API Key格式、模型名称拼写、tool目录路径是否存在。若提示model name 'deepseek-chat' not found in provider 'openai-compatible'，说明你在hermes setup中填错了模型ID，不是删掉重配，而是执行hermes model set deepseek-chat --provider openai-compatible修正。
