在 Android Termux 环境下安装 Hermes Agent 的踩坑与解决实践

发表于 分类于 阅读时长 ≈ 2 分钟
本文记录了在 Android 设备的 Termux 终端中部署 Nous Research 的 Hermes Agent 时所经历的真实踩坑过程。从解决一键脚本的静默死锁，到突破网络代理限制，再到攻克 Rust 交叉编译与 psutil 平台封杀等底层技术难点，最终沉淀出一套稳定可靠的手动编译安装方案。

1. 业务场景与核心挑战

运行环境：

  • 操作系统：Android (基于 Termux 终端模拟器)
  • 开发工具：Python 3.13, Clang, Rust 工具链
  • 业务场景：在移动端设备上本地化部署并运行 Hermes Agent AI 代理工具。

核心挑战：
移动端 Termux 环境虽然提供了高度还原的 Linux 体验，但由于其底层依然依赖 Android 的 API 和特殊的包管理机制，在安装包含大量 C/Rust 扩展的复杂 Python 项目时，极其容易遭遇依赖缺失、编译死锁和平台兼容性阻断。

2. 官方一键脚本的初次尝试与死锁陷阱

踩坑重现：
起初，我尝试直接使用官方提供的一键安装脚本，期望能快速完成部署：

1
curl -fsSL [https://hermes-agent.nousresearch.com/install.sh](https://hermes-agent.nousresearch.com/install.sh) | bash

输出结果（异常卡死）：

1
2
3
4
5
6
7
Detected: android (termux)
→ Termux detected — using Python's stdlib venv + pip instead of uv
→ Checking Termux Python...
→ Installing Python via pkg...
date: /data/data/com.termux/cache/apt/pkgcache.bin: No such file or directory

WARNING: apt does not have a stable CLI interface. Use with caution in scripts.

脚本在输出最后一行警告后，便彻底失去响应，长时间假死。

原因剖析：
这是 Termux 下典型的管道符执行“暗坑”。官方安装脚本在后台调用了 pkg 或 apt 来安装依赖，而包管理器在此刻弹出了类似 [Y/n] 的交互式确认提示。由于使用了 curl ... | bash 的无头执行方式，终端的交互界面被直接屏蔽，导致脚本在此处死锁等待，永远等不到用户的输入。

应对策略：
使用 Ctrl+C 强行打断死锁，改为手动执行带 -y 参数的静默更新与基础依赖安装：

1
2
pkg update && pkg upgrade -y
pkg install python git clang rust make -y

3. 突破网络连通性与命令行代理限制

跨过了基础依赖的坑后，再次运行安装脚本，结果又遭遇了网络相关的阻断。

输出结果（网络报错）：

1
2
3
4
Node.js v26.3.1 installed via pkg
→ Checking internet connectivity for package install and web tools...
Warning: Could not reach [https://duckduckgo.com/](https://duckduckgo.com/)
Warning: Termux network prerequisites may be incomplete.

紧接着，在脚本尝试静默安装 pkg-config libffi openssl 时，又一次因为 [Y/n] 提示陷入了卡死。

原因剖析：

  1. 根证书缺失： Termux 环境初始未携带完整的 CA 证书链，导致 HTTPS 请求被拒。
  2. 终端不走系统 VPN： Android 系统状态栏虽然显示梯子已连接，但 Termux 中的命令行工具（如 curl, pip）默认处于直连状态，无法穿透网络限制拉取国外资源。

应对策略：
补全证书和所有底层依赖，并手动注入本地代理端口的环境变量（假设代理软件的本地 HTTP 端口为 7890）：

1
2
3
4
5
6
7
8
9
10
# 1. 安装证书与剩余底层依赖
pkg install -y ca-certificates curl pkg-config libffi openssl ripgrep ffmpeg

# 2. 强制当前终端会话走本地代理
export http_proxy="[http://127.0.0.1:7890](http://127.0.0.1:7890)"
export https_proxy="[http://127.0.0.1:7890](http://127.0.0.1:7890)"

# 3. 验证网络连通性
curl -I [https://duckduckgo.com/](https://duckduckgo.com/)
# 返回 HTTP/2 200 即代表代理生效

4. 攻克硬核编译阶段的底层报错

在解决了网络与基础包问题后，脚本进入了漫长的 pip install 阶段，但这恰恰是最痛苦的环节。

坑一：Cryptography 模块编译“假死”与 Android API 变量缺失

由于 Android 环境没有预编译的 Python Wheel 包，安装 cryptography 时需要本地化调用 Rust 编译，终端只显示一行 Installing build dependencies ... | 并伴随着手机发热。

为了打破这种“不知道是不是死机”的黑盒状态，我通过 Ctrl+C 打断，并开启 -v 详细日志模式手动安装：

1
pip install cryptography==46.0.7 -v

输出结果（Maturin 构建崩溃）：

1
2
3
Error: maturin failed
Caused by: Failed to determine Android API level. Please set the ANDROID_API_LEVEL environment variable.
Error running maturin: Command '['maturin', 'pep517', 'write-dist-info', ...] returned non-zero exit status 1.

原因剖析： 在 Android 上使用 maturin 编译 Rust 扩展库时，编译器必须知道具体的系统 API 级别，否则无法链接底层的 C 库。官方一键脚本遗漏了这一关键变量的注入。

解决方案： 向系统注册 API 级别变量，然后重试编译。

1
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"

坑二：Psutil 平台硬编码封杀

当终于熬过长达十几分钟的 Rust 编译后，安装脚本又在构建 psutil 模块时彻底阵亡。

输出结果（致命错误）：

1
2
3
platform android is not supported
error: subprocess-exited-with-error
× Getting requirements to build wheel did not run successfully.

原因剖析： psutil 的官方开发者在最新版本中硬编码封杀了 Android 平台。一旦检测到运行在安卓下，就会直接抛出该异常并罢工。此时，盲目拉取最新依赖的官方“一键安装脚本”已经彻底宣告破产。

5. 最终落地：摒弃一键脚本的手动完美方案

经过以上一连串的排雷，我得出一个结论：在 Termux 这种特殊环境下，必须放弃高度封装的一键脚本，采用完全透明的手动分步部署。

以下是最终整理出的一套百分百能跑通的纯净安装流程：

步骤一：准备系统环境与代码

1
2
3
4
5
6
7
8
9
10
11
# 1. 开启代理（根据实际情况替换端口）
export http_proxy="[http://127.0.0.1:7890](http://127.0.0.1:7890)"
export https_proxy="[http://127.0.0.1:7890](http://127.0.0.1:7890)"

# 2. 安装所有底层工具链
pkg update && pkg upgrade -y
pkg install -y git python clang rust make pkg-config libffi openssl nodejs ripgrep ffmpeg ca-certificates

# 3. 拉取源码
git clone [https://github.com/NousResearch/hermes-agent.git](https://github.com/NousResearch/hermes-agent.git)
cd hermes-agent

步骤二：构建受限的虚拟环境

这一步是整个过程的灵魂。我们必须注入 API 变量，并使用官方仓库中针对 Termux 专门编写的约束文件（constraints-termux.txt），以锁定那些未经安卓封杀的老版本依赖（如老版本的 psutil）。

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 初始化虚拟环境
python -m venv venv
source venv/bin/activate

# 2. 注入 Android 交叉编译生命线变量
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"

# 3. 升级核心构建工具
python -m pip install --upgrade pip setuptools wheel

# 4. 执行受限安装（这一步会包含源码编译，请保持屏幕常亮等待约 10-20 分钟）
pip install -e '.[termux]' -c constraints-termux.txt

步骤三：验证与运行

1
2
# 安装完成后，调出配置向导
hermes setup

6. 总结与实践建议

  1. 一键脚本的适用边界：curl | bash 这类脚本在标准 Linux 发行版上体验极佳，但在高度定制的移动端环境（如 Termux）中，往往会因为交互式提示、缺少预编译二进制包、甚至由于开发者恶意封杀平台而失效。掌控底层构建逻辑是移动端开发的必修课。
  2. 抵抗系统杀后台机制：在手机上成功跑起 Agent 后，最大的敌人变成了 Android 的电池优化机制。建议在 Termux 中执行 termux-wake-lock 开启 CPU 唤醒锁，并配合 tmux 工具将 Hermes 挂载在后台会话中运行，防止 UI 界面被清理导致进程意外中断。