Hermes Agent v0.18.0 启动失败需按顺序排查：先用 hermes logs 定位 ERROR/Traceback 日志；确认 Python 3.11 环境及 pip 路径一致；校验 config.yaml 与 .env 中模型名和 API Key 匹配；检查 8080 端口是否被占用；最后确保 shell PATH 包含 ~/.local/bin 并 source 配置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
新手安装 Hermes Agent v0.18.0 后执行 hermes start 命令却无任何响应、终端瞬间返回、服务进程查不到，说明启动流程在初始化阶段就被阻断，必须从日志源头开始逐层定位，跳过任一环节都可能反复失败。
先捕获真实错误日志
终端“一闪而过”的输出不可信，真正关键的堆栈信息被写入后台日志流。执行 hermes logs 让日志持续滚动；若你启用了网关（如飞书/微信），同步运行 hermes gateway logs。按 Ctrl+C 中断后，用方向键 ↑ 回溯最后 15 行，重点找以 ERROR、Traceback、Failed to start 或 Address already in use 开头的行——这行就是故障源头，后面所有操作都围绕它展开。
【不要跳过这一步】直接重装或改配置却不看日志，90%会重复踩坑。
验证 Python 3.11 环境是否就位
Hermes Agent v0.18.0 严格绑定 Python 3.11，用 3.10 或 3.13 都会触发 pyo3 崩溃或语法解析中断，且错误常伪装成“模块缺失”。
运行 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 两文件的字段名没对齐。
方法一：手动校验
打开 ~/.hermes/config.yaml，找到 model.default: 字段，记下值（如 openai/gpt-4o）；再打开 ~/.hermes/.env，确认存在对应大写变量名（如 OPENAI_API_KEY=sk-xxx），且值以 sk- 开头、首尾无空格。
方法二：命令修复（推荐）
在终端中输入 hermes model openai/gpt-4o（请将 openai/gpt-4o 替换为实际模型路径），该命令会强制 Hermes 重新加载模型配置，绕过环境变量初始化问题。
检查端口是否被占用
网关组件默认监听 8080 端口；若该端口已被其他进程占用，将直接导致启动失败并报错 Address already in use。
第一步：查询端口占用情况
Linux/macOS 执行 lsof -i :8080，Windows 执行 netstat -ano | findstr :8080。
第二步：记录输出中的 PID 数字（如 12345）
第三步：终止占用进程
Linux/macOS 执行 kill -9 12345，Windows 执行 taskkill /PID 12345 /F。
第四步：重新启动网关服务，观察日志中是否出现 Listening on http://0.0.0.0:8080 提示。
确认 shell 环境变量已生效
安装后未刷新 shell 配置会导致 hermes 命令不可识别，进而使启动脚本因找不到主程序而静默失败。
执行命令重新加载当前 shell 配置：source ~/.bashrc（bash 用户）或 source ~/.zshrc（zsh 用户）。
检查 ~/.local/bin 是否已存在于 PATH 中：echo $PATH | grep -o '.local/bin'。若未命中，手动追加路径并生效：echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc。
最后验证命令可用性：hermes --version，预期输出类似 hermes v0.18.0 (v2026.7.22)。
