许多用户在部署 Hermes Agent 时，常常在安装环节受阻：依赖解析失败、C 扩展编译中断，甚至刚启动就闪退。根本原因其实只有一个——该项目强制依赖 CPython 3.11 运行时环境，而你系统默认的 Python 版本可能是 3.9、3.12 或 3.13。这些版本均不在官方兼容清单内。当 uv 或 pip 意外调用了高版本解释器时，pyo3 与 tiktoken 的构建过程会直接崩溃；而低版本则缺少 typing.UnionType 等关键语法特性。因此，问题并不出在安装脚本本身，而在于 Python 版本没有选对。
更具体地说，在安装过程中，如果系统默认的 Python 并非 3.11，uv 的环境判定逻辑很容易被干扰——即便脚本声称会“自动创建 3.11 环境”，系统级 python3 的存在依然可能让路径走偏。在 WSL2 或 macOS 上，这个陷阱几乎无法避开。下面梳理的每一步都来自实战积累，严格执行就能顺利绕过雷区。
验证并锁定系统级 Python 3.11
这一步必须优先搞定，否则后续所有操作都有可能在错误的解释器上运行，导致环境迅速被污染。
先执行 python3 --version 查看当前默认版本。如果输出不是 【3.11.x】，那就不能直接运行安装脚本——哪怕脚本宣称会自动创建环境，系统级 python3 的存在也会干扰 uv 的判断逻辑。
执行 uv python install 3.11 下载并注册 Python 3.11 解释器（无需 root 权限）。确认安装成功：运行 uv python list，输出中应看到 3.11.x (default) 或标记为 installed 的版本。
创建隔离虚拟环境
方法一：使用 uv 创建专用环境（推荐）
运行 uv venv ~/.hermes/venv --python 3.11，路径必须固定为 【~/.hermes/venv】，这是 Hermes 最新脚本默认查找的位置，改成其他路径会导致后续命令无法识别该环境。然后激活环境：source ~/.hermes/venv/bin/activate。验证解释器路径：which python 输出必须是 ~/.hermes/venv/bin/python，而不是 /usr/bin/python 或 /opt/homebrew/bin/python3。
方法二：使用 python3.11 -m venv（当 uv 不可用时）
先确认 python3.11 命令存在。如果没有，Ubuntu 上执行 sudo apt install python3.11 python3.11-venv，macOS 上执行 brew install python@3.11。然后运行 python3.11 -m venv ~/.hermes/venv 创建环境。注意：不要添加 --system-site-packages 参数——Hermes 不需要继承系统包，加上反而会引发冲突。
强制使用 3.11 执行安装流程
第一步：下载安装脚本到本地。执行 curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o ~/install.sh，借助 ghfast.top 加速镜像可有效避免超时。
第二步：赋予执行权限。chmod +x ~/install.sh
第三步：绕过脚本自动探测逻辑。这是关键所在——使用 python3.11 显式调用脚本，而不是 bash install.sh 或 ./install.sh。后两者会调用系统默认 python，即便激活了 venv 也无效。执行 python3.11 ~/install.sh。
第四步：刷新 PATH。安装完成后，hermes 命令会被写入 ~/.local/bin，但当前终端不会自动识别。必须运行 source ~/.zshrc（macOS/Zsh）或 source ~/.bashrc（Linux/Bash）。验证：echo $PATH 输出中应包含 ~/.local/bin，且 which hermes 返回该路径。
手动修复依赖（当自动安装中断时）
① 克隆源码（使用 GitCode 镜像加速）：git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git ~/.hermes/hermes-agent
② 进入目录并激活环境：cd ~/.hermes/hermes-agent && source ~/.hermes/venv/bin/activate
③ 修改 pyproject.toml 中的 Python 版本约束：用编辑器打开 pyproject.toml，找到 requires-python = "^3.11" 这一行——如果该行不存在或者值是 "^3.12"，请手动改为 【^3.11】，否则 pip install -e ".[all]" 会拒绝安装。
④ 强制重装依赖：pip install -r requirements.txt --force-reinstall --no-deps
⑤ 安装本地包：pip install -e ".[all]"