CentOS 7 上安装 Hermes Agent 0.21.3 实录：从 Python 语法错误到成功启动

最近在一台长期用于 EDA 的 CentOS 7 机器上安装 Hermes Agent 0.21.3。过程里连续遇到了 Python 版本混用、依赖解析冲突、Pillow 编译失败等问题。

最终 Hermes 正常启动，openai、Pillow、pillow-heif 都安装完成，CLI 可以正常执行。

本文记录整个排查过程和最终可复现方案。

初始问题：Hermes 一启动就报 `future feature annotations is not defined`

最开始直接执行 Hermes。

env -u LD_LIBRARY_PATH \
  "$HOME/.hermes/hermes-agent/hermes" --version

立即报错。

Traceback (most recent call last):
  File "/home/EDA/.hermes/hermes-agent/hermes", line 10, in <module>
    from hermes_cli.main import main
  File "/home/EDA/.hermes/hermes-agent/hermes_cli/main.py", line 16, in <module>
    import hermes_bootstrap
  File "/home/EDA/.hermes/hermes-agent/hermes_bootstrap.py", line 16
    from __future__ import annotations
SyntaxError: future feature annotations is not defined

看到这个错误时，第一反应通常是代码有问题。

实际上这里的问题在于执行脚本时调用到了错误版本的 Python。

先确认 Hermes 的 shebang。

head -n 3 "$HOME/.hermes/hermes-agent/hermes"

输出。

#!/usr/bin/env python3
"""
Hermes Agent CLI launcher.

Hermes 使用的是系统找到的 python3。

接着检查虚拟环境里的 Python。

env -u LD_LIBRARY_PATH \
  "$HOME/.hermes/hermes-agent/venv/bin/python" --version

结果正常。

Python 3.11.16

再直接用 venv 中的 Python 启动 Hermes。

env -u LD_LIBRARY_PATH \
  "$HOME/.hermes/hermes-agent/venv/bin/python" \
  "$HOME/.hermes/hermes-agent/hermes" --version

立即成功。

Hermes Agent v0.21.3 (2026.9.14)
Python: 3.11.16
OpenAI SDK: Not installed

到这里已经能确认一件事。

Hermes 本身没有问题，问题出在系统环境找到的 Python 版本过低。

检查虚拟环境，发现核心依赖没有安装

虽然 CLI 能启动，但版本信息显示：

OpenAI SDK: Not installed

查看当前环境。

env -u LD_LIBRARY_PATH \
  "$HOME/.local/bin/uv" pip list \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python"

结果只有两个包。

Package     Version
----------- -------
pillow      12.2.0
pillow-heif 0.18.0

Hermes 的主体依赖根本没有安装进去。

查看项目配置。

grep -nE '^\[project\]|^dependencies =|pillow-heif|openai' \
  "$HOME/.hermes/hermes-agent/pyproject.toml"

能看到：

dependencies = [
  ...
  "openai==2.24.0",
  ...
]

按理说安装后应该有大量依赖。

第一次安装失败：约束文件把自己锁死了

为了控制 Pillow 版本，先创建了约束文件。

cat > /tmp/hermes-constraints.txt <<'EOF'
pillow==12.2.0
pillow-heif==0.18.0
EOF

随后执行安装。

uv pip install \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python" \
  -c /tmp/hermes-constraints.txt \
  -e "$HOME/.hermes/hermes-agent"

结果依赖求解直接失败。

Because hermes-agent==0.21.3 depends on pillow-heif>=1.4.0,<2
and pillow-heif==0.18.0

requirements are unsatisfiable

这里的问题很直接。

约束文件要求：

pillow-heif==0.18.0

项目配置要求：

pillow-heif>=1.4.0,<2

两边互相冲突。

依赖求解器没有办法给出结果。

Dry Run 暴露真正的问题：Hermes 想升级到 Pillow 12.3.0

去掉约束文件后做一次 Dry Run。

uv pip install \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python" \
  -e . \
  --dry-run

输出里出现关键内容。

- pillow==12.2.0
+ pillow==12.3.0

Hermes 安装时准备升级 Pillow。

继续搜索配置文件。

grep -n "12.3.0" pyproject.toml

发现隐藏配置。

"Pillow==12.3.0",

之前只修改了小写的 pillow 项。

真正生效的是大写的 Pillow 依赖。

这也是后面安装始终尝试拉取 12.3.0 的原因。

Pillow 12.3.0 编译失败

继续安装后出现新的错误。

核心报错如下。

src/libImaging/Mode.c:30:5:
错误：只允许在 C99 模式下使用‘for’循环初始化声明

对应代码类似：

for (size_t i = 0; i < ...; i++) {

编译器提示：

使用 -std=c99 或 -std=gnu99 来编译您的代码

问题已经非常明确。

Pillow 12.3.0 没有拿到可用 wheel，开始走源码编译。

而当前 CentOS 7 的编译环境无法满足其构建要求。

继续折腾编译器没有意义。

直接固定回已验证可用的 Pillow 12.2.0 更简单。

修改 pyproject.toml 固定 Pillow 版本

确认项目中的 Pillow 配置。

grep -nE '^[[:space:]]*"?[Pp]illow' pyproject.toml

修改后内容如下。

"Pillow==12.2.0",
"pillow-heif==0.18.0",

再次 Dry Run。

uv pip install \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python" \
  -e . \
  --dry-run

这次输出已经没有 Pillow 升级动作。

Resolved 64 packages
Would install 62 packages

说明依赖求解已经恢复正常。

正式安装成功

执行正式安装。

uv pip install \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python" \
  -e "$HOME/.hermes/hermes-agent"

安装完成。

Installed 62 packages

其中包括：

openai==2.24.0
httpx==0.28.1
fastapi==0.141.1
rich==14.3.3
pydantic==2.13.4

验证关键依赖

直接导入验证。

env -u LD_LIBRARY_PATH \
"$HOME/.hermes/hermes-agent/venv/bin/python" -c '
import openai, PIL, pillow_heif
print("openai:", openai.__version__)
print("Pillow:", PIL.__version__)
print("pillow-heif:", pillow_heif.__version__)
'

输出。

openai: 2.24.0
Pillow: 12.2.0
pillow-heif: 0.18.0

三个核心组件全部正常。

验证 Hermes CLI

检查版本。

env -u LD_LIBRARY_PATH \
"$HOME/.hermes/hermes-agent/venv/bin/python" \
"$HOME/.hermes/hermes-agent/hermes" --version

输出。

Hermes Agent v0.21.3 (2026.9.14)
Install method: git
Python: 3.11.16
OpenAI SDK: 2.24.0

再检查帮助信息。

env -u LD_LIBRARY_PATH \
"$HOME/.hermes/hermes-agent/venv/bin/python" \
"$HOME/.hermes/hermes-agent/hermes" --help

完整命令列表正常显示。

包括：

chat
setup
doctor
dashboard
gateway
sessions
memory
plugins
update

说明 CLI 已经进入可用状态。

让 `hermes` 直接可执行

当前最可靠的启动方式仍然是：

env -u LD_LIBRARY_PATH \
"$HOME/.hermes/hermes-agent/venv/bin/python" \
"$HOME/.hermes/hermes-agent/hermes"

如果每次都输入这么长一串命令并不现实。

可以建立一个包装脚本。

mkdir -p "$HOME/bin"

cat > "$HOME/bin/hermes" <<'EOF'
#!/bin/bash
exec env -u LD_LIBRARY_PATH \
  "$HOME/.hermes/hermes-agent/venv/bin/python" \
  "$HOME/.hermes/hermes-agent/hermes" "$@"
EOF

chmod +x "$HOME/bin/hermes"

然后把目录加入 PATH。

echo 'export PATH="$HOME/bin:$PATH"' >> "$HOME/.bashrc"
source "$HOME/.bashrc"

确认。

which hermes

应返回：

/home/EDA/bin/hermes

此后直接执行：

hermes

或者：

hermes setup

即可启动。

操作清单速览

确认 Hermes 使用 Python 3.11 虚拟环境。
使用 venv/bin/python 直接启动 Hermes 排除系统 Python 干扰。
检查 uv pip list，确认核心依赖是否安装。
检查 pyproject.toml 中真实生效的 Pillow 配置。
将 Pillow==12.3.0 修改为 Pillow==12.2.0。
保持 pillow-heif==0.18.0。
使用 uv pip install -e . 重新安装。
验证 openai、Pillow、pillow-heif 导入成功。
创建 wrapper 脚本处理 LD_LIBRARY_PATH。
将 wrapper 所在目录加入 PATH。

FAQ

为什么会出现 `future feature annotations is not defined`？

Hermes 实际调用到了错误版本的 Python。使用虚拟环境中的 Python 3.11 启动后问题消失。

为什么 `OpenAI SDK` 显示未安装？

虚拟环境里只有 pillow 和 pillow-heif，Hermes 的主体依赖并未完成安装。

为什么约束文件会导致依赖无法解析？

约束文件固定了：

pillow-heif==0.18.0

而项目配置要求的是另一个版本范围，依赖求解器无法同时满足两组要求。

为什么安装时会尝试升级 Pillow？

pyproject.toml 中仍存在：

"Pillow==12.3.0"

安装器按这个版本进行解析。

Pillow 12.3.0 为什么失败？

安装过程进入源码编译阶段，CentOS 7 当前编译环境无法满足其构建要求。

如何确认 Hermes 已经安装成功？

执行：

hermes --version

看到：

OpenAI SDK: 2.24.0

即可说明核心依赖已经生效。

为什么启动命令里一直带 `env -u LD_LIBRARY_PATH`？

EDA 环境会污染动态库搜索路径，Hermes 独立运行时需要避开这些环境变量。

后续最推荐的启动方式是什么？

使用包装脚本：

hermes

由脚本自动切换到 Hermes 自己的 Python 环境并清理 LD_LIBRARY_PATH。

CentOS 7 安装 Hermes Agent 0.21.3 全攻略：从 Python 报错到 Pillow 编译，手把手解决