在安装 Hermes Agent v0.19.0 时，如果遇到 Python 版本报错，通常是因为当前环境中的 Python 版本不符合其严格的支持要求。该版本仅兼容 Python 3.12.3，低于 3.11 或高于 3.12.2 的版本都会导致问题。使用不兼容的版本可能引发 tiktoken 加载失败、pyo3 扩展崩溃、安装脚本中途退出等故障。

接下来，我们将逐步解析如何解决这个版本兼容性问题。

检查当前 Python 版本并识别问题类型

首先，查看系统中所安装的 Python 版本：在终端中运行 python3 --version 或 python --version。

• 若输出为 3.9.x 或 3.10.x，说明版本过低，未达到 v0.19.0 的最低要求。
• 若输出为 3.13.x 或 3.14.x，说明版本过高，tiktoken 和 llama-cpp-python 的 C 扩展将编译失败。
• 若输出为 3.12.0～3.12.2，虽然进入了支持区间，但 v0.19.0 要求的是 3.12.3+，需要升级补丁版本。
• 若输出已经是 3.12.3+ 但安装依然报错，很可能是系统默认 Python 被误调用，而脚本实际运行在旧环境中。

使用 uv 创建并绑定 Python 3.12.3 环境

推荐方法：直接安装指定补丁版本。执行 uv python install 3.12.3，这一步会将精确版本下载到 uv 的版本管理器中。

然后创建专用虚拟环境：uv venv --python 3.12.3 ~/.hermes/venv。

【注意】不要用 python3.12 创建环境，必须显式指定 3.12.3，否则可能拉取到 3.12.2，导致后续模型加载失败。

激活环境：source ~/.hermes/venv/bin/activate。

验证解释器路径：which python3 应返回 ~/.hermes/venv/bin/python3；再执行 python3 -c "import sys; print(sys.version)"，输出必须是以 3.12.3 开头。

绕过脚本自动探测，强制用 3.12.3 执行安装

第一步：下载安装脚本到本地
curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o install.sh

第二步：赋予执行权限
chmod +x install.sh

第三步：使用刚安装好的 3.12.3 显式运行，完全跳过脚本内部的版本探测逻辑
python3.12.3 install.sh

这一步能彻底规避因系统默认 Python 过高（如 3.13）导致的 uv 环境判定错误、pip 行为异常或依赖解析中断。

手动安装失败后的兜底方案

方法一：克隆源码 + 强制覆盖依赖

执行 git clone https://github.com/NousResearch/hermes-agent.git && cd hermes-agent。

确保已激活 3.12.3 环境后，修改 pyproject.toml 中的 requires-python = "^3.12.3"。

运行 pip install --force-reinstall --no-deps -r requirements.txt，跳过已有包的版本校验。

再执行 pip install --no-deps -e . 安装 Hermes 本体。

方法二：使用 uv 替代 pip 完成最终同步

在激活的 3.12.3 环境中，执行：uv pip install -r requirements.txt。

uv 的依赖解析比 pip 更严格，能自动剔除与 3.12.3 不兼容的预编译 wheel，优先选择源码构建路径，大幅降低 pyo3/tiktoken 编译失败的概率。