Hermes Agent 启动脚本排障3 步修复依赖缺失与启动报错【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent第一次 clone 下来就跑不通装完依赖hermes 命令却提示找不到这类问题基本都卡在 Hermes Agent 启动脚本的依赖检查环节。下面按看它干了什么 → 对症状 → 逐步修的路子带你把环境配到能正常启动。一、安装脚本背后在做什么4 步依赖检查顺序把官方一键安装脚本的行为拆开看它按固定顺序做四件事确认 uv 和 Python 3.11 就位缺失就自动补装.python-version 里锁定的就是 3.11处理 Node.js、ripgrep、ffmpeg 等外围工具Windows 上还会单独打包一份便携 Git Bash在 ~/.hermes 下创建并初始化虚拟环境装全量依赖把 hermes 入口命令软链进 PATH之后你才能直接敲 hermes 进入对话。记住这个顺序后面定位问题就只看两步卡在第 1 步是工具链没就位卡在第 4 步多半是 shell 配置没生效。二、三类启动故障按症状快速定位失败基本集中在三个地方先对症状再用对应命令确认症状常见原因判断命令结果符合即确认构建依赖时报版本不兼容系统 Python 太旧没拉到 3.11python3 --version 输出不是 3.11装完敲 hermes 提示 command not found入口不在 PATH或新 shell 没加载配置command -v hermes 无输出会话中途运行时报缺文件虚拟环境建在了源码目录里被会话中的清理命令删掉ls ~/.hermes/venvs 不存在或目录名不在预期位置第三条来自 CONTRIBUTING.md 的明确警告虚拟环境放在 agent 自己的工作目录里一次 rm -rf 或重建操作就能把它清掉正在跑的会话随之中断。三、修复环境装工具链、建 venv、配 PATH第 1 步装 uv确认 3.11 可用。uv --version || curl -LsSf https://astral.sh/uv/install.sh | sh uv python list | grep 3.11第 2 步建虚拟环境装全量依赖。uv venv ~/.hermes/venvs/hermes-dev --python 3.11 source ~/.hermes/venvs/hermes-dev/bin/activate uv pip install -e .[all]注意路径.python-version 写的是 3.11venv 建在 ~/.hermes/venvs/ 而不是仓库目录里。第 3 步配 PATH跑诊断。ln -sf ~/.hermes/venvs/hermes-dev/bin/hermes ~/.local/bin/hermes grep -q .local/bin ~/.bashrc || echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc hermes doctorhermes doctor 是官方给的自检入口输出全绿才算修完。仓库里还有 .envrcdirenv 用户可以直接拿来做环境加载钩子。四、跨发行版与跨系统差异点对照环境入口方式默认安装位置容易踩的点Linux / macOS / WSL2终端一行安装脚本~/.hermes不同发行版的包管理器只管系统层虚拟环境把依赖锁在固定位置差异被隔掉了Windows 原生PowerShell 安装%LOCALAPPDATA%\hermesGit Bash 由安装流程自动带一份便携版已装 Git 则直接复用bash 和 zsh 的区别只剩最后一步PATH 追加到 ~/.bashrc 还是 ~/.zshrc。系统层差异apt、dnf、Homebrew基本不用你操心因为关键依赖都进虚拟环境了。五、上线前自查清单逐项打勾Python 版本python3 --version 是 3.11虚拟环境位置在源码树之外依赖完整性python -c import hermes 无报错命令可用性command -v hermes 能打印路径PATH 持久化重开终端后 hermes 依旧可执行诊断输出hermes doctor 无红灯配置就绪.env 里的 provider 和 key 已按 .env.example 填好全部打勾后按顺序执行这三行git clone https://gitcode.com/GitHub_Trending/he/hermes-agent cd hermes-agent bash install.sh中途报错回到第二、三节按症状对号入座逐项过一遍清单。【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考