在安卓手机 Termux 上装 Hermes Agent:6 次踩坑、1 次解药、1.5 小时

一

想在我的安卓手机上跑 NousResearch 的 Hermes Agent。

听起来很美好 —— 手机上有个能学、能记、还能给我推消息的 agent。

然后就开干了。

二、为什么是 termux?

Hermes Agent 自带一个 “Tier 2: Termux support“ 的指南。一句话装:curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash。

Tier 2 是什么意思?best-effort。官方明说:”Commits to main may break these packages at any point in time.”——主分支的 commit 随时可能 break 我的安装。

嗯。我还是点了”开干”。

三、第 1 次 fail:Python 版本不对

装到一半:

1	ERROR: Package 'hermes-agent' requires a different Python: 3.14.6 not in '<3.14,>=3.11'

我的手机 termux 自带 Python 3.14.6。但 Hermes 写明要求 <3.14 —— 作者担心 Rust 包(比如 pydantic-core)在 cp314 wheel 没出来前会强行走源码编译然后挂掉。

那装个 Python 3.12 不就行了?pyenv 装一个。

四、第 2-4 次 fail:termux bionic libc 缺东西

pyenv install 3.12.12,15 分钟编译,失败:

1	fatal error: 'spawn.h' file not found

termux 的 libc 不是 glibc,是 Android 的 bionic。bionic 默认不暴露 spawn.h(POSIX posix_spawn 的头文件)。

修法:pkg install libandroid-spawn —— 这个包专门补 spawn.h。

继续编译。又 fail:

1
2
3

error: call to undeclared function 'getloadavg'
error: call to undeclared function 'fexecve'
error: call to undeclared function 'getrandom'

每一个都是 POSIX 函数,bionic libc 都不 declare。我试了 ac_cv_func_X=no、CFLAGS=-Wno-error=implicit-function-declaration,都失败 —— Python 源码里用 #pragma GCC diagnostic error 强制把 warning 转 error,环境变量根本盖不住。

试 termux 的 11 个官方 patch(termux-packages/packages/python/0001..0011-*.patch)。失败 —— 这些 patch 是给 Python 3.14.6(termux 当前版本)写的,我用 3.12.12,行号对不上。

到这一步我几乎想放弃了。

五、第 5 次:换思路

回头看官方文档:

Python 3.14.6 + termux python package

termux 官方 已经帮我把 Python 3.14.6 编译好了,还打了 11 个 patch、build script 写了一堆 ac_cv_func_X=no。

我花了 1 小时想绕过它,完全是浪费时间。

新策略:用 system python 3.14.6,改 Hermes 的 Python 约束。

但 Hermes 说 <3.14 啊?

六、找解药:GitHub PR #60041

搜 GitHub 找到 PR #60041(kyssta-exe,2026-07-14):

pydantic-core 2.46.4 (via pydantic 2.13.4) now ships cp314 wheels, so the <3.14 ceiling is no longer needed to prevent maturin source builds.
Raises requires-python from >=3.11,<3.14 to >=3.11,<3.15

PR 标的 closed,但内容里写得很清楚 —— pydantic-core 已经在 PyPI 发 cp314 wheel 了。

我去 PyPI 验证:

1	pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_aarch64.whl (1.9MB)

✅ 真的有 aarch64 cp314 wheel。

我手动 sed -i 's|>=3.11,<3.14|>=3.11,<3.15|' pyproject.toml 改了 Hermes 的本地仓库。

七、第 6 次 fail:psutil android not supported

1 2	× Getting requirements to build wheel did not run successfully. ╰─> platform android is not supported

psutil 7.2.2 setup 脚本检查 sys.platform.startswith('linux') —— termux 上 sys.platform == 'android',直接拒绝。

但 Hermes 仓库里早就给我准备好了解决方案:scripts/install_psutil_android.py。

这个脚本 patch 源码:LINUX = sys.platform.startswith(("linux", "android")),然后编译。

跑了 3 分钟,装好了。

八、完整装机

# 1. 装工具链 (一次)
pkg update && pkg upgrade -y
pkg install -y openssh clang rust make pkg-config libffi openssl \
  ca-certificates curl ffmpeg ripgrep nodejs git
pkg install -y libandroid-spawn   # 关键

# 2. 拉 Hermes
git clone https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent
cd ~/.hermes/hermes-agent

# 3. 改 Python 约束 (PR #60041)
sed -i 's|>=3.11,<3.14|>=3.11,<3.15|' pyproject.toml

# 4. 建 venv + 装 psutil (用 Hermes 自带 shim)
python -m venv venv
source venv/bin/activate
export ANDROID_API_LEVEL=$(getprop ro.build.version.sdk)
pip install --upgrade pip setuptools wheel
python scripts/install_psutil_android.py --pip "$(pwd)/venv/bin/pip"

# 5. 装 Hermes 主体 (~10-15 分钟,Rust 编译 ~30 个包)
pip install -e ".[termux]" -c constraints-termux.txt

# 6. 加 PATH
ln -sf "$(pwd)/venv/bin/hermes" "$PREFIX/bin/hermes"

# 7. 验证
hermes version
# Hermes Agent v0.18.2 (2026.7.7.2)
hermes doctor

九、复盘 — 5 条永久规则

规则 1:编译 Python 在 termux 上是死路,直接用 system 3.14

bionic libc 缺几十个 POSIX 函数。Python 源码 #pragma diagnostic error 强制转 error。ac_cv_func / CFLAGS 都不够。别编译,用 termux 自带 python。

规则 2:psutil 在 Android 必须用 Hermes 自带 shim

pip install psutil 失败 → 用 python scripts/install_psutil_android.py --pip <pip_path>。

规则 3:Hermes Python 约束要 <3.15(不是 <3.14)

官方文档说 <3.14,但 pydantic-core 2.46.4 cp314 wheel 已发布。手动 sed 改 pyproject.toml,等官方合并。

规则 4:ANDROID_API_LEVEL 必须 export

Rust maturin 需要这个变量。export ANDROID_API_LEVEL=$(getprop ro.build.version.sdk)。

规则 5:termux 没有 /tmp / which

mkdir -p ~/tmp(系统 /tmp 不存在)
用 command -v 代替 which

十、一些反思

1. 不要凭”我以为”做决定

我一开始的隐含假设是:”termux 应该能装 Python 3.12,那就装 3.12。”但 termux 自带 3.14 + 一堆 patch,这就是答案。先看官方现状,再决定怎么做。

2. 解药往往在 GitHub PR 里

PR #60041 被标 closed(可能作者没合并),但内容是对的。不要因为”closed”就觉得”没解药”。

3. 不要重复造轮子

termux 的 11 个 patch 是给 Python 3.14.6 写的。Hermes 的 install_psutil_android.py 是给 Hermes 写的。这两个轮子都存在,只是我没第一时间找。

十一、数字

踩坑次数: 6
找解药次数: 1 (GitHub PR #60041)
总耗时: ~1.5 小时 (大部分等编译)
最终磁盘占用: 653 MB (194 个 Python 包)
hermes version 跑通: < 1 秒

配置 API key / Telegram gateway 等可选步骤待办。Hermes 本身在手机 termux 跑通了。

写于 2026-07-18 下午
现场:6 次编译失败 + GitHub PR 救场 + psutil shim 救场
主题:在 Android Termux 上装 agent 的工程踩坑 + 找解药路径
关联:~/openclaw-wiki/tools/termux-hermes-install/SKILL.md