启动失败时应依次排查：一、重载shell配置并确认path含~/.local/bin；二、确保python为3.11且pip与python3路径一致；三、核对config.yaml与.env中模型及api key配置；四、检查端口占用并修改gateway端口；五、激活hermes虚拟环境并补全依赖。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您执行 hermes start 或直接运行 Hermes Agent 服务时进程立即退出、无响应或报错闪退，则说明启动流程在初始化阶段遭遇阻断。以下是针对该问题的多种独立排查与修复路径：
一、验证并重载 shell 环境变量 PATH
安装后未刷新 shell 配置会导致 hermes 命令不可识别，进而使启动脚本因找不到主程序而静默失败。
1、执行命令重新加载当前 shell 配置：source ~/.bashrc（bash 用户）或 source ~/.zshrc（zsh 用户）。
2、检查 ~/.local/bin 是否已存在于 PATH 中：echo $PATH | grep -o '.local/bin'。
3、若未命中，手动追加路径并生效：echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc。
4、验证命令可用性：hermes --version，预期输出类似 hermes v0.9.0 (v2026.4.8)。
二、检查 Python 运行时版本兼容性
Hermes Agent 严格依赖 Python 3.11，使用低于 3.10 或高于 3.13 的版本均会触发初始化崩溃，表现为 ImportError、SyntaxError 或 pyo3 构建失败。
1、确认当前默认 Python 版本：python3 --version。
2、若版本为 3.9.x 或 3.13.x，需强制切换至 3.11：pyenv install 3.11.9 && pyenv global 3.11.9（需已安装 pyenv）。
3、验证 pip 与 python3 指向一致：which python3 && which pip3，二者路径前缀应完全相同。
4、重建 Hermes 虚拟环境：rm -rf ~/.hermes/venv && hermes setup。
三、定位并清除模型认证配置冲突
“Model not recognized” 或 “AuthenticationError: Invalid API key” 类错误常导致主服务在模型加载阶段中止，日志中通常伴随空指针或 Provider 初始化失败提示。
1、打开配置文件 ~/.hermes/config.yaml，确认 model.default 字段值（如 openai/gpt-4o）拼写准确且格式合规。
2、检查 ~/.hermes/.env 中是否存在对应大写变量名（如 OPENAI_API_KEY），值是否以 sk- 开头且无首尾空格。
3、绕过环境变量缓存，强制重设模型：hermes model openai/gpt-4o。
4、运行完整配置向导覆盖旧设置：hermes setup --force。
四、排查端口占用与网关监听冲突
网关组件（gateway）默认绑定 8080 或 9090 端口，若被 nginx、另一个 Hermes 实例或调试服务占用，将导致整个 Agent 启动流程卡死在 gateway 初始化阶段。
1、检测端口占用情况：Linux/macOS 执行 lsof -i :8080，Windows 执行 netstat -ano | findstr :8080。
2、记录输出中的 PID 数值，终止对应进程：Linux/macOS 执行 kill -9 12345，Windows 执行 taskkill /PID 12345 /F。
3、修改网关端口配置：编辑 ~/.hermes/application.yml，将 server.port 改为未被占用的数值（如 8081）。
4、重启服务：hermes gateway start，观察日志是否出现 NettyHttpServer started on port 8081。
五、审查依赖完整性与虚拟环境隔离状态
在 WSL2 或多 Python 环境下，系统 pip 安装的包无法被 Hermes 自带的 venv 访问，导致启动时抛出 ModuleNotFoundError（如 lark-oapi、aiohttp、uvloop）。
1、进入 Hermes 虚拟环境根目录：cd ~/.hermes/venv。
2、激活该环境：source bin/activate（Linux/macOS）或 Scripts\activate.bat（Windows WSL2）。
3、批量校验关键依赖是否存在：python -c "import aiohttp, lark_oapi, uvloop"。
4、若报错缺失模块，使用当前激活环境的 pip 安装：pip install aiohttp lark-oapi uvloop --force-reinstall。
