首先验证PATH是否包含~/.local/bin并重载shell配置；其次确保Python为3.11版本并重建venv；接着检查8080等默认端口是否被占用并释放或修改；Windows用户必须使用WSL2环境；最后确认config.yaml语法正确、权限正常且API Key字段完整有效。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试启动Hermes Agent，但终端无响应、命令不识别或进程立即退出，则可能是由于环境缺失、路径未加载、端口冲突或配置异常所致。以下是解决此问题的步骤：
一、验证命令是否在PATH中并重新加载shell配置
安装脚本通常将可执行文件写入~/.local/bin，但当前shell会话未加载该路径，导致hermes命令无法识别。
1、执行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。
4、再次执行source ~/.bashrc，然后运行hermes --version验证。
二、检查Python版本兼容性并强制使用3.11
Hermes Agent明确要求Python 3.11，使用3.13等高版本将触发pyo3扩展崩溃或依赖解析失败。
1、运行python3 --version确认当前版本。
2、若显示3.13.x或低于3.11，需切换至3.11：uv python install 3.11。
3、重建虚拟环境：uv venv --python 3.11 ~/.hermes/venv。
4、激活该环境后重试启动：source ~/.hermes/venv/bin/activate，再执行hermes。
三、排查端口占用与网关监听冲突
Hermes Agent网关默认监听8080或9090端口，若被其他进程占用，会导致启动阻塞或静默失败。
1、在Linux/macOS上执行：lsof -i :8080；在Windows上执行：netstat -ano | findstr :8080。
2、从输出中提取PID列数值（例如12345）。
3、终止该进程：kill -9 12345（Linux/macOS）或taskkill /PID 12345 /F（Windows）。
4、修改配置文件application.yml，将server.port更改为未被占用的端口（如8081），再重启服务。
四、确认系统环境支持并启用WSL2（Windows用户必做）
Hermes Agent原生不支持Windows PowerShell/CMD，必须运行于类Unix环境；WSL2是官方唯一认可的Windows兼容方案。
1、运行wsl --install启用WSL2并安装Ubuntu 24.04发行版。
2、启动Ubuntu终端，执行uname -a，确认输出含Linux内核标识。
3、检查基础工具：which bash curl git python3 pip3，任一缺失需补全安装。
4、在WSL2终端中完整执行安装流程，严禁在Windows原生终端中直接运行安装脚本。
五、检查配置文件语法完整性与权限状态
YAML格式错误、关键字段缺失或文件权限不足，均会导致Agent启动时跳过初始化并静默退出。
1、运行hermes config path获取真实配置路径，例如/home/user/.hermes/config.yaml。
2、执行ls -l /home/user/.hermes/config.yaml，确认文件存在且属主为当前用户。
3、若权限异常，修复：sudo chown $USER:$USER /home/user/.hermes/config.yaml && chmod 644 /home/user/.hermes/config.yaml。
4、打开该文件，确保model:区块下包含provider:、api_key:、base_url:三项，且api_key值为非空字符串并包裹在双引号内。
