psutil 装不上导致 Termux 里的 Hermes Agent v0.19.0 崩溃：Android 解释器版本错配排查与修复指南

适用环境：Android + Termux，Hermes Agent 通过 pip 安装。

本文记录两个独立问题。第一个是 psutil 装不上的问题，也是真正的根因；第二个是 hermes --version 的包内代码缺陷。两者互不相干，分别处理。

故障现象

问题一：pip 装 psutil 直接失败

python3.13 -m pip install psutil \
  --extra-index-url https://termux-user-repository.github.io/pypi/

输出：

Collecting psutil
  Using cached psutil-7.2.2.tar.gz (493 kB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... error
  error: subprocess-exited-with-error

  × Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [1 lines of output]
      platform android is not supported
      [end of output]

注意这条报错发生在 Getting requirements to build wheel 阶段，编译还没开始。psutil 的 setup.py 主动判断平台，Android 直接拒绝，不存在"编译不过"这一步。

问题二：hermes --version 报 NameError

hermes --version
# Hermes Agent v0.19.0 (2026.7.20)
# Traceback (most recent call last):
#   File ".../hermes_cli/main.py", line 388, in <module>
#     if _try_termux_ultrafast_version():
#   ...
# NameError: name 'PROJECT_ROOT' is not defined

版本号打印出来了，紧接着崩溃。这是 main.py 导入期的代码缺陷，见文末"踩坑记录"第 9 条。

第一步：确认 pip 失败的原因，以及 extra-index-url 为什么没用

报错文本 platform android is not supported 来自 psutil 源码包，不是 pip 也不是 Termux 的问题。pip 拿到的是 PyPI 上的 psutil-7.2.2.tar.gz（源码包，需要本地编译），而 psutil 不支持 Android。

--extra-index-url 没有起到预期作用，原因有两层：

pip 会同时查询主索引（pypi.org）和 extra index，哪个先给出可用候选就用哪个。PyPI 上有 sdist，pip 就选了它，没有回落到 extra index。
https://termux-user-repository.github.io/pypi/ 本身也不提供 psutil 的 aarch64 wheel，即便回落也没有可用的包。

所以这条路走不通，要换 psutil 的来源。

第二步：查清解释器版本，这是整个问题的关键

先看 python3 到底指向哪个版本：

ls -la /data/data/com.termux/files/usr/bin/python3*
# python3 -> python3.14
# python3.13
# python3.14

当前 python3 指向 python3.14。而 Termux 仓库里 python-psutil 的编译目标是 3.14：

pkg show python-psutil
# Package: python-psutil
# Version: 7.2.2-2

dpkg -L python-psutil | grep site-packages
# /data/data/com.termux/files/usr/lib/python3.14/site-packages/psutil

确认它只落在 3.14 的 site-packages 下：

find /data/data/com.termux/files/usr/lib/python3.14/site-packages/psutil -name "*.so"
# .../psutil/_psutil_linux.abi3.so

用 3.14 解释器导入，正常：

/usr/bin/python3.14 -c "import psutil; print(psutil.__version__)"
# 7.2.2

到这里结论清楚了：pkg install python-psutil 装的 psutil 只对 python3.14 有效。如果 venv 建在 3.13 上，sys.path 里只有 /usr/lib/python3.13，看不到 3.14 的 site-packages，import 必然失败。

这解释了此前踩过的坑：venv 里出现过 psutil-android 7.2.6，那是从 PyPI 装进去的另一份，ABI 与 3.13 + bionic 环境不匹配，导入时段错误（exit 139）。两条错误路径混在一起，看起来像同一个问题，实际是版本错配的两个面。

第三步：把 venv 建在 python3.14 上

既然 psutil 只能从 Termux 仓库拿，venv 就必须和仓库的编译目标对齐，也就是 3.14。

deactivate                      # 若当前已在旧环境内
rm -rf ~/hermes_venv
python3.14 -m venv ~/hermes_venv
source ~/hermes_venv/bin/activate

确认版本与 sys.prefix：

python --version
# Python 3.14.x

python -c "import sys; print(sys.prefix)"
# /data/data/com.termux/files/home/hermes_venv

不要用裸 python3 -m venv。Termux 上 python3 的指向会随包更新变化，混装不同版本的 wheel 会放大问题，显式写版本号。

第四步：先装 psutil，再装 Hermes

顺序很重要。psutil 是卡点，先把它单独验证通过，再去装 Hermes，否则依赖解析会把两者混在一起，出问题分辨不清。

# 1. 从 Termux 仓库装 python-psutil（不要指定版本后缀，让它跟随仓库当前目标）
pkg install -y python-psutil

# 2. 验证（这一步必须过）
python -c "import psutil; print(psutil.__version__)"
# 7.2.2

注意两点：

不要写 pkg install python3.13 python-psutil。这会试图装 3.13 的解释器，而仓库里的 python-psutil 是给 3.14 编译的，装完仍然导入不了。只装 python-psutil，它的依赖会自己带对解释器。
装完必须重跑第 2 步验证。不通过就不要继续装 Hermes。

第五步：装 Hermes Agent 主体

--no-deps 是刻意为之，避免 pip 从 PyPI 重新拉 psutil（那份在 Android 上装不上）覆盖掉前面装好的 Termux 版本：

pip install --no-deps hermes-agent

# 手动补齐运行依赖
pip install httpx pydantic pyyaml toml click rich aiohttp prompt-toolkit croniter

第六步：反复补齐缺失的包

--no-deps 的代价是依赖要自己凑。启动 hermes，缺什么装什么：

hermes
# ModuleNotFoundError: No module named 'xxx'
pip install xxx

循环几次直到 hermes 能正常进入界面。本地这次装齐的清单（pip list 实测）：

hermes-agent       0.19.0
psutil-android     7.2.6
httpx              0.28.1
pydantic           2.13.5
pydantic_core      2.46.5
pydantic-settings  2.15.0
PyYAML             6.0.3
toml               0.10.2
click              8.5.0
rich               15.0.0
aiohttp            3.14.3
prompt_toolkit     3.0.53
croniter           6.2.4

清单里的 psutil-android 7.2.6 是 venv 里残留的那份 PyPI 包，不是 pkg install python-psutil 的结果。它导入时段错误（exit 139），必须在 venv 里卸掉，否则会盖住仓库版本：

pip uninstall -y psutil-android
python -c "import psutil; print(psutil.__version__)"   # 应输出仓库版 7.2.2

第七步：让 Termux 每次启动自动进入虚拟环境

echo 'source $HOME/hermes_venv/bin/activate' >> ~/.bashrc

之后每次打开 Termux 都在 venv 里，hermes 直接可用。注意 venv 路径写在 ~/.bashrc 里做了存在性无关的硬编码，如果你以后改目录名，这一行也要跟着改。

验证清单

python --version                                        # 3.14.x
python -c "import psutil; print(psutil.__version__)"    # 7.2.2，不崩
hermes                                                  # 能正常进入界面
hermes --version                                        # 版本号正常打印（见下方说明）

踩坑记录

platform android is not supported 是 psutil 上游主动拒绝 Android，不是编译失败。看到这条就知道必须换来源，不要在 pip 参数上想办法。
--extra-index-url 不是"PyPI 不行就用备用"的意思。pip 会把主索引和 extra index 一起查，PyPI 上只要有 sdist 就会被选中。要真正绕开 PyPI，用 --index-url 或直接走系统包管理器。
venv 的解释器版本必须和 psutil 的来源对齐。Termux 仓库的 python-psutil 只编译到当前默认 Python 版本，venv 建在别的版本上必然导入失败。建之前先 ls -la $(which python3*) 看清指向。
不要用裸 python3 -m venv。Termux 上 python3 的软链会随包更新变化（本次就是 3.13 变 3.14），显式写版本号。
pip list 里同时出现 psutil 和 psutil-android 要警惕。两份来源不同的 psutil 会互相覆盖，venv 里能看到的只有一份，先 pip uninstall 清掉 PyPI 那份再验证。
pkg install 只写 python-psutil，不要顺手加 python3.13 之类的版本包，会把解释器版本带偏。
pip install --no-deps hermes-agent 是必要操作，否则 pip 会把 psutil 重新拉成 Android 装不上的版本，前面的修复白做。
依赖手动补齐后再启动，缺一个包就装一个，--no-deps 之后没有自动化兜底。
hermes --version 报 NameError: name 'PROJECT_ROOT' is not defined 是包内缺陷，不影响主程序。main.py 第 367 行引用了 PROJECT_ROOT，第 388 行在模块顶层就调用，而它直到第 461 行才被赋值。看到这个报错不用回滚 psutil 的修复。

版本说明

本文涉及的版本号均为本次实测结果（python --version、pip list、hermes --version）。

补充：hermes --version 在当前版本的 Termux 快速版本路径（_try_termux_ultrafast_version()）下会抛 NameError: name 'PROJECT_ROOT' is not defined，版本号本身能正常打印，紧接着的 Install directory 一行崩掉。这是包内代码语句顺序问题，不影响主程序，hermes 可以正常使用。版本会随时间变化，复现时请以自己的实际输出为准，尤其是 PROJECT_ROOT 这类代码级问题可能在新版本中已修复。

如果你觉得本文有用，请点赞，收藏，转发

你有什么问题，请留言，我来帮你解答。