在华为 Mate 20 Pro 上安装 Hermes Agent 完整总结

一、设备环境

• 手机型号：华为 Mate 20 Pro
• 处理器：麒麟 980（ARM64 架构）
• 运行环境：Termux（从 F-Droid 或 github 安装，不能用 Google Play 版本太旧）
• Python 版本：3.11（使用 venv311，系统自带的 Python 3.13 兼容性差）

二、安装步骤

1. 安装 Termux 基础依赖

pkg update && pkg install python git nodejs openssh

2. 准备 Python 虚拟环境

Hermes 仓库通常位于 /data/data/com.termux/files/home/hermes-agent，里面有两个虚拟环境：

• venv/ — Python 3.13（不推荐）
• venv311/ — Python 3.11（推荐，预装部分依赖）

使用 venv311 作为主环境。

3. 安装纯 Python 依赖

pip install python-dotenv fire httpx rich tenacity prompt_toolkit \
  pyyaml requests jinja2 debugpy fal-client edge-tts croniter \
  aiohttp psutil ipython parallel-web

4. 安装核心 SDK（必须指定版本）

pip install --no-deps openai==1.35.0
pip install --no-deps anthropic==0.39.0

5. 安装 Hermes Agent 本体

cd /data/data/com.termux/files/home/hermes-agent
pip install --no-deps -e .

6. 锁定依赖版本（防止意外升级）

cat > ~/.config/pip/constraints.txt << 'EOF'
openai==1.35.0
anthropic==0.39.0
pydantic==1.10.26
httpx==0.27.2
EOF

cat >> ~/.config/pip/pip.conf << 'EOF'

[install]
constraint = ~/.config/pip/constraints.txt
EOF

7. 创建 jiter 兼容桩（关键步骤）

由于 jiter 是 Rust 编写的，无法在 Termux 的 armv8l 架构上编译，必须创建纯 Python 兼容层：

cat > venv311/lib/python3.11/site-packages/jiter.py << 'STUB'
"""jiter compatibility stub for Termux/Android."""
import json
from typing import Any

def from_json(data, **kwargs):
    if isinstance(data, (bytes, bytearray)):
        data = data.decode("utf-8")
    return json.loads(data, **kwargs)

def to_json(obj, **kwargs):
    return json.dumps(obj, **kwargs)

class JiterError(Exception):
    pass
STUB

8. 验证安装

venv311/bin/python3 hermes --help
venv311/bin/python3 hermes doctor

三、遇到的核心问题与解决方案

问题 1：maturin 编译失败 —— Unsupported Android architecture: armv8l

现象：
安装 jiter、pydantic-core、cryptography 等含 Rust 代码的包时全部失败。

原因：
Termux 将 uname -m 报告为 armv8l（32 位兼容模式），但 maturin 的 Rust 代码不认识这个架构字符串。

尝试过但失败的方案：

• 用 sitecustomize.py 修补 platform.machine() —— 无效，maturin 用的是原生系统调用
• 设置 CARGO_BUILD_TARGET=armv7-linux-androideabi —— 无效，maturin 在交叉编译前就检查了
• 伪造 uname 命令 —— 无效，maturin 是编译好的 Rust 二进制文件，不走 PATH

最终方案：

• 所有依赖用 --no-deps 安装，跳过 Rust 编译步骤
• 核心 SDK 锁定到不需要 jiter 的版本：
  • openai==1.35.0（>=1.36 需要 jiter，会直接崩溃）
  • anthropic==0.39.0（0.95+ 需要 jiter）
  • pydantic==1.10.26（v2 需要 pydantic-core，也是 Rust）
  • httpx==0.27.2（0.28+ 移除了 proxies 参数，openai 1.35.0 内部需要这个参数）

问题 2：Agent 运行后卡住不动

现象：
启动 Hermes Agent 后，AI 没有响应，长时间无输出。

排查方法：
查看日志文件：

cat /data/data/com.termux/files/home/.hermes/logs/agent.log

发现的根因：
日志中反复出现 ModuleNotFoundError: No module named 'jiter' 错误，导致 API 调用不断重试失败，请求队列堆积，最终整个 Agent 卡死。

解决方案：

1. 确认 jiter 兼容桩是否正确创建在 venv311/lib/python3.11/site-packages/jiter.py
2. 确认 openai==1.35.0（不能用更高版本）
3. 删除残留的 gateway PID 文件，重启 Agent：

   rm ~/.hermes/gateway.pid
   hermes gateway start
   

问题 3：连接微信时卡住

现象：
配置微信（WeCom/企业微信或微信机器人通道）后，消息收发没有反应，Agent 卡住。

排查过程：

1. 查看 messaging 工具的日志输出
2. 发现 Termux 上缺少微信 SDK 所需的系统依赖
3. 某些第三方微信库（如 itchat、WeChatPYAPI）在 ARM Android 上无法正常工作

解决方案：

方案 A（推荐）：改用 Telegram/Discord 等替代平台
Termux 对这些平台的支持更好，安装简单：

pip install --no-deps python-telegram-bot discord.py

在 config.yaml 中配置 Telegram Bot Token 即可使用，稳定性远超微信方案。

方案 B：企业微信（WeCom）Webhook 模式
如果必须用微信体系，使用企业微信的 Webhook 方式：

• 不需要微信 SDK，纯 HTTP 调用
• 在 Hermes 中通过 webhook 工具与企业微信对接
• 避免了 Python 微信库在 Termux 上的兼容性问题

方案 C：在手机上用系统键盘的语音输入
Termux 上语音识别方案（faster-whisper、vosk、pocketsphinx）都无法在 armv8l 上编译。最实用的替代方案是用手机自带的键盘语音输入，把语音转文字后发送给 Agent。

问题 4：pydantic v2 需要 pydantic-core（Rust 编译失败）

现象：
安装 pydantic >=2.0 时编译失败。

解决方案：
锁定到 pydantic==1.10.26（v1 版本），Hermes 完全兼容。

问题 5：httpx 版本不兼容

现象：
安装 httpx 0.28+ 后，openai SDK 报错：

Client.__init__() got an unexpected keyword argument 'proxies'

解决方案：
锁定到 httpx==0.27.2，这个版本保留了 proxies 参数。

四、最终可用的依赖版本表

包名	版本	说明
openai	1.35.0	>=1.36 需要 jiter
anthropic	0.39.0	0.95+ 需要 jiter
pydantic	1.10.26	v2 需要 pydantic-core
httpx	0.27.2	0.28+ 缺少 proxies 参数
python-telegram-bot	latest	通过 --no-deps 安装
discord.py	latest	通过 --no-deps 安装

五、让 Hermes 全局可用

创建全局命令包装器：

cat > /data/data/com.termux/files/usr/bin/hermes << 'WRAPPER'
#!/data/data/com.termux/files/home/hermes-agent/venv311/bin/python3
import sys
sys.path.insert(0, '/data/data/com.termux/files/home/hermes-agent')
from hermes_cli.main import main
main()
WRAPPER

chmod +x /data/data/com.termux/files/usr/bin/hermes

之后在任何目录下都可以直接运行 hermes --help。

六、后续建议

1. 优先使用 Telegram/Discord 而非微信 —— Termux 上生态兼容性更好
2. 永远用 --no-deps 安装带 Rust 扩展的包 —— 避开 maturin 编译
3. 用 hermes doctor 定期检查环境 —— 及时发现缺失的工具
4. 日志是诊断的第一手段 —— 遇到卡住先看 ~/.hermes/logs/agent.log
5. 不要用 Python 3.13 —— Termux 上 3.11 更稳定