Hermes_Agent启动失败？5步排查修复指南

执行hermes start后终端像被按了暂停键一样瞬间返回——没有日志滚动，没有进度条，甚至连个像样的错误提示都没有。这可不是什么好兆头，说明Hermes Agent在初始化阶段就被直接挡在了门外。遇到这种情况，最忌讳的就是瞎猜乱试，必须按步骤来：日志→Python版本→模型配置→端口→依赖，五步逐层排查，跳过任何一个环节，都可能重蹈覆辙。

先别着急卸载重装，第一步永远是：让日志开口说话。

第一步：立刻捕获真实错误日志

启动失败时终端里那一闪而过的报错信息，基本可以当作没看见——真正的堆栈细节早就被重定向到后台日志流里去了。执行hermes logs，让日志持续输出；如果你还启用了飞书或微信网关，同步运行hermes gateway logs。按Ctrl+C停掉日志流后，用方向键向上翻最后15行，重点搜索ERROR、Traceback、Failed to start或Address already in use——那一行就是事故源头，后续所有操作都围绕它展开。

别跳过这一步。不看日志直接改配置或者强行重装，90%的概率会在同一个坑里摔两次。

第二步：验证Python版本与虚拟环境一致性

Hermes Agent对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是否和Python指向同一个解释器：分别运行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-开头，头尾不能有空格。

这里推荐一个更省事的办法：直接在终端里运行/model openai/gpt-4o（把模型名字换成你自己的）。这个命令会强制Hermes重新加载模型配置，绕过.env文件读取失败的问题。Windows/WSL2用户尤其适合用这一招。

第四步：检查网关端口是否被占用

网关默认监听8080或9090端口，如果被Chrome插件、本地开发服务或者僵尸进程占了，Hermes会悄无声息地退出，只留下一句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，在gateway:区块下加一行port: 8081，保存后重启就行。

第五步：补全缺失依赖并激活虚拟环境

依赖缺失在Windows/WSL2上最常见，典型报错是ModuleNotFoundError: No module named 'lark-oapi'。注意，这些包必须装进Hermes自己的虚拟环境里，用系统的pip装根本没效果。先找到虚拟环境路径（通常是~/.hermes/venv），然后激活它：source ~/.hermes/venv/bin/activate（Linux/macOS）或~.hermesvenvScriptsactivate.bat（Windows）。在激活状态下用pip install lark-oapi aiohttp cryptography把缺失的模块补上。装完后执行deactivate退出虚拟环境，最后运行hermes start验证一下。