hermes agent启动无响应须按五步排查：先执行hermes logs捕获error/traceback等关键日志；再确认python3 --version为3.11.x且pip3路径一致；接着校验config.yaml中model.default与.env中对应大写api_key匹配，并检查model.provider字段；然后用lsof或netstat查8080端口占用并确认server.enabled为true；最后若用jar包，需验证java -version≥11且有目录写入权限。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Hermes Agent v0.18.2 或 v0.17.0 安装完成后执行 hermes start 却无任何响应、终端瞬间返回、进程未创建，说明服务在初始化阶段即被阻断，必须从日志源头切入，不能直接重装或改配置。
第一步：立刻捕获真实错误日志
启动失败时终端“一闪而过”的输出不可信，真正关键的堆栈信息被重定向到后台日志流中。执行 hermes logs 让日志持续滚动；若你启用了网关（如飞书/微信），同步运行 hermes gateway logs。
按 Ctrl+C 中断日志流后，用方向键 ↑ 回溯最后 15 行，重点找以 ERROR、Traceback、Failed to start 或 Address already in use 开头的行——这行就是故障源头，后面所有操作都围绕它展开。
【不要跳过这一步】 直接重装或改配置却不看日志，90% 会重复踩坑。
第二步：验证 Python 环境是否严格匹配 v0.18.2/v0.17.0 要求
v0.18.2 和 v0.17.0 均强制依赖 Python 3.11，使用 3.10 或 3.13 会导致 pyo3 扩展崩溃、语法解析中断，且错误常伪装成“模块缺失”或“ImportError”。
运行 python3 --version，确认输出为 Python 3.11.x；如果不是，执行 pyenv install 3.11.9 && pyenv global 3.11.9（需已安装 pyenv）。
检查 pip 是否指向同一解释器：which python3 和 which pip3 输出路径前缀必须完全一致，例如都是 /home/user/.pyenv/versions/3.11.9/bin/。
若路径不一致，说明 pip 安装的包不会被 Hermes 加载——此时必须删掉旧环境：rm -rf ~/.hermes/venv，再执行 hermes setup 重建。
第三步：核对模型配置与 API Key 是否精准对齐
“Model not recognized” 或 “AuthenticationError: Invalid API key” 这类错误，99% 源于 config.yaml 和 .env 两文件的字段名没对齐，尤其 v0.18.2 新增了 provider 分层校验逻辑。
方法一：手动校验
打开 ~/.hermes/config.yaml，找到 model.default: 字段，记下值（如 openai/gpt-4o）；再打开 ~/.hermes/.env，确认存在对应大写变量名（如 OPENAI_API_KEY=sk-xxx），且值以 sk- 开头、首尾无空格。
方法二：绕过缓存强制重设
执行 hermes model openai/gpt-4o（将 openai/gpt-4o 替换为你实际使用的模型标识），该命令会跳过配置文件直接注入运行时上下文。
方法三：检查 provider 显式声明（v0.18.2 必须）
在 config.yaml 中确认存在 model.provider: 字段，值必须与 .env 中 API KEY 变量前缀一致，例如 model.provider: openai → .env 中必须含 OPENAI_API_KEY。
第四步：检查端口占用与 server 配置是否生效
v0.17.0 和 v0.18.2 默认监听 8080 端口，若被其他进程占用，会直接报错 Address already in use 并退出，不写入常规日志。
① 查询端口占用：Linux/macOS 执行 lsof -i :8080，Windows 执行 netstat -ano | findstr :8080。
② 若输出含 PID（如 12345），执行 kill -9 12345（Linux/macOS）或 taskkill /PID 12345 /F（Windows）释放端口。
③ 打开 ~/.hermes/config.yaml，确认 server.enabled 值为小写 true（YAML 对布尔值大小写敏感），且 server.port 不为 0 或负数。
若你修改过端口，请同步更新 hermes gateway start 的 --port 参数，否则网关无法连接主服务。
第五步：验证 Java 运行时是否干扰（仅限 JAR 包部署用户）
部分用户下载的是 hermes-agent.jar 启动包，而非 CLI 版本。该包基于 Java 构建，必须依赖 JRE 11+，与 Python 环境完全隔离。
执行 java -version，确认输出含 11 或更高主版本号；若提示 command not found，需前往 Adoptium 下载并安装 Temurin-11 JRE。
安装后执行 which java，确保路径指向新安装的 JRE 目录；然后用调试模式启动：java -jar hermes-agent.jar --debug，观察控制台首个报错行。
若出现 java.nio.file.AccessDeniedException，说明当前用户对 logs/ 或 workspace/ 目录无写入权限，需执行 chmod -R 755 logs workspace（Linux/macOS）或右键目录→属性→安全→添加当前用户完全控制权限（Windows）。
