可使用hermesdoctor工具四步诊断：一、运行hermesdoctor --version验证命令可用性；二、执行hermesdoctor check进行基础环境自检；三、启用hermesdoctor check --verbose排查隐性异常；四、用hermesdoctor check --port 8080验证端口连通性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已安装HermesAgent但不确定其运行环境是否完备，可借助hermesdoctor工具执行多维度诊断。以下是运行该诊断工具的具体方式：
一、验证hermesdoctor命令可用性
该步骤用于确认系统能否识别hermesdoctor命令，是后续所有诊断的前提。若命令未被识别，说明安装未生效或PATH环境变量未正确配置。
1、打开终端（Linux/macOS）或命令提示符/PowerShell（Windows）。
2、输入hermesdoctor --version并按回车。
3、观察输出结果：若显示类似hermesdoctor 1.2.0的版本号，则命令已就绪；若提示command not found或'hermesdoctor' is not recognized as an internal or external command，需检查PATH或重新执行安装脚本。
二、执行基础环境自检
此模式不依赖额外参数，自动扫描Python运行时、必需Python模块、核心配置文件（如config.yaml）、默认端口占用等关键项，覆盖绝大多数初始部署失败场景。
1、在终端中执行hermesdoctor check。
2、等待扫描完成（通常耗时5–15秒）。
3、逐行查看输出中的标记：所有条目均显示[PASS]表示基础环境就绪；任一出现[FAIL]，须依据其后附带的提示信息定位具体缺失项。
三、启用详细日志模式排查隐性异常
当基础检查全部通过但HermesAgent仍无法启动时，可能存在模块导入失败、配置解析中断或初始化异常等静默错误。该模式将输出完整加载链路与堆栈信息，适用于深度验证。
1、运行hermesdoctor check --verbose。
2、滚动查看输出内容，重点关注以ERROR或WARNING开头的行。
3、若出现类似Failed to import module 'hermesagent.core'的提示，表明核心包未正确安装，或当前Python环境存在隔离冲突（如误激活了其他venv）。
四、验证服务端口连通性
HermesAgent默认监听本地TCP端口（如8080或3000），此步骤独立于进程状态检查，专用于确认网络层是否可达，可暴露防火墙拦截、端口被占、绑定地址非localhost等问题。
1、确保HermesAgent服务已尝试启动（例如已执行hermesagent start）。
2、执行hermesdoctor check --port 8080（请将8080替换为实际配置的端口号）。
3、若返回Port 8080 is reachable，说明监听成功；若返回Connection refused，则服务进程未运行，或绑定地址非127.0.0.1/localhost。
