跳到主要内容

在 Android 上使用 Termux 运行 Hermes

这是通过 Termux 在 Android 手机上直接运行 Hermes Agent 的经过验证的路径。

该方案为你在手机上提供一个可工作的本地 CLI，以及目前确认可在 Android 上干净安装的核心附加功能。

经验证路径支持哪些功能？​

经验证的 Termux 包含以下组件：

  • Hermes CLI
  • cron 支持
  • PTY/后台终端支持
  • MCP 支持
  • Honcho 内存支持
  • ACP 支持

具体对应如下：

python -m pip install -e '.[termux]' -c constraints-termux.txt

目前尚未包含在验证路径中的功能？​

一些功能仍需要桌面/服务器风格的依赖项，这些依赖项尚未发布适用于 Android 的版本，或尚未在手机上验证通过：

  • .[all] 当前不支持 Android
  • voice 附加功能受阻于 faster-whisper -> ctranslate2，而 ctranslate2 未发布 Android 的 wheel 包
  • Termux 安装器会跳过自动浏览器 / Playwright 启动流程
  • Docker 基于的终端隔离功能在 Termux 内不可用

这并不妨碍 Hermes 作为原生手机 CLI 代理良好运行——只是意味着推荐的移动端安装路径有意比桌面/服务器安装路径更窄。

选项 1：一键安装器​

Hermes 现在提供一个对 Termux 友好的安装路径：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

在 Termux 中，安装器会自动执行以下操作：

  • 使用 pkg 安装系统包
  • 使用 python -m venv 创建虚拟环境
  • 使用 pip 安装 .[termux]
  • 将 hermes 链接到 $PREFIX/bin，使其保留在 Termux 的 PATH 中
  • 跳过未经测试的浏览器 / WhatsApp 启动流程

如果你希望查看具体命令或需要调试安装失败问题，请使用下方的手动安装路径。

选项 2：手动安装（完全显式）​

1. 更新 Termux 并安装系统包​

pkg update
pkg install -y git python clang rust make pkg-config libffi openssl nodejs ripgrep ffmpeg

为何需要这些包？

  • python —— 运行时 + 虚拟环境支持
  • git —— 克隆/更新仓库
  • clang, rust, make, pkg-config, libffi, openssl —— 用于在 Android 上构建部分 Python 依赖项
  • nodejs —— 可选 Node 运行时，用于超出验证核心路径的实验
  • ripgrep —— 快速文件搜索
  • ffmpeg —— 媒体 / TTS 转换

2. 克隆 Hermes​

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

如果你已克隆但未包含子模块：

git submodule update --init --recursive

3. 创建虚拟环境​

python -m venv venv
source venv/bin/activate
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install --upgrade pip setuptools wheel

ANDROID_API_LEVEL 对于基于 Rust / maturin 的包（如 jiter）非常重要。

4. 安装经验证的 Termux 包​

python -m pip install -e '.[termux]' -c constraints-termux.txt

如果你只需要最小核心代理，也可以使用以下命令：

python -m pip install -e '.' -c constraints-termux.txt

5. 将 hermes 加入 Termux PATH​

ln -sf "$PWD/venv/bin/hermes" "$PREFIX/bin/hermes"

$PREFIX/bin 已在 Termux 的 PATH 中，因此该操作可使 hermes 命令在新 shell 中持久可用，无需每次重新激活虚拟环境。

6. 验证安装​

hermes version
hermes doctor

7. 启动 Hermes​

hermes

配置模型​

hermes model

或直接在 ~/.hermes/.env 中设置密钥。

稍后重新运行完整的交互式设置向导​

hermes setup

手动安装可选的 Node 依赖项​

经验证的 Termux 路径有意跳过 Node/浏览器启动流程。如果你希望后续进行实验：

npm install

请将 Android 上的浏览器 / WhatsApp 工具链视为实验性功能，直到另有文档说明。

故障排除​

安装 .[all] 时提示 No solution found​

请改用经验证的 Termux 包：

python -m pip install -e '.[termux]' -c constraints-termux.txt

当前障碍是 voice 附加功能：

  • voice 依赖 faster-whisper
  • faster-whisper 依赖 ctranslate2
  • ctranslate2 未发布 Android 的 wheel 包

uv pip install 在 Android 上失败​

请改用 Termux 路径，使用标准库虚拟环境 + pip：

python -m venv venv
source venv/bin/activate
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e '.[termux]' -c constraints-termux.txt

jiter / maturin 报告 ANDROID_API_LEVEL 问题​

安装前显式设置 API 级别：

export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install -e '.[termux]' -c constraints-termux.txt

hermes doctor 提示 ripgrep 或 Node 缺失​

使用 Termux 包安装它们：

pkg install ripgrep nodejs

安装 Python 包时构建失败​

请确保已安装构建工具链：

pkg install clang rust make pkg-config libffi openssl

然后重试：

python -m pip install -e '.[termux]' -c constraints-termux.txt

手机上的已知限制​

  • Docker 后端不可用
  • 通过 faster-whisper 实现的本地语音转录在验证路径中不可用
  • 浏览器自动化设置被安装器有意跳过
  • 某些可选附加功能可能可用，但目前仅 .[termux] 被记录为经过验证的 Android 包

如果你遇到新的 Android 特定问题，请在 GitHub 上提交问题并附上：

  • 你的 Android 版本
  • termux-info
  • python --version
  • hermes doctor
  • 完整的安装命令和错误输出