跳到主要内容

在 Android 上使用 Termux 运行 Hermes

这是通过 Termux 直接在 Android 手机上运行 Hermes Agent 的已测试路径。

它为您提供手机上可工作的本地 CLI，以及目前已知可在 Android 上干净安装的核心额外功能。

已测试路径支持哪些功能？​

已测试的 Termux 套件安装了：

  • Hermes CLI
  • 定时任务支持
  • PTY/后台终端支持
  • Telegram 网关支持（手动/尽力而为的后台运行）
  • MCP 支持
  • Honcho 记忆支持
  • ACP 支持

具体对应：

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

尚未纳入已测试路径的功能？​

一些功能仍需要桌面/服务器风格的依赖，这些依赖未针对 Android 发布，或尚未在手机上验证：

  • .[all] 目前在 Android 上不受支持
  • voice 扩展因 faster-whisper -> ctranslate2 而受阻，ctranslate2 未发布 Android wheels
  • Termux 安装程序跳过了自动浏览器/Playwright 引导
  • Docker 终端隔离在 Termux 内不可用
  • Android 可能仍会挂起 Termux 后台任务，因此网关持久性是尽力而为，而非正常的托管服务

这并不妨碍 Hermes 作为手机原生 CLI Agent 正常工作——只是意味着推荐的移动安装比桌面/服务器安装有意更窄。

选项 1：一键安装​

Hermes 现在提供 Termux 感知的安装路径：

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

在 Termux 上，安装程序会自动：

  • 使用 pkg 安装系统软件包
  • 使用 python -m venv 创建虚拟环境
  • 先尝试广泛的 .[termux-all] 额外功能，然后回退到较小的 .[termux] 额外功能（然后是基础安装）——curl 安装程序会自动匹配此顺序
  • 将 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

如果您只想要最小核心 Agent，这也可以：

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/浏览器引导。如果您之后想尝试浏览器工具：

pkg install nodejs-lts
npm install

浏览器工具会自动在其 PATH 搜索中包含 Termux 目录（/data/data/com.termux/files/usr/bin），因此无需额外的 PATH 配置即可发现 agent-browser 和 npx。

在另有文档说明之前，将 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 wheels

uv pip install 在 Android 上失败​

改用带标准库 venv + pip 的 Termux 路径：

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] 和 .[termux-all] 被记录为已测试的 Android 套件

如果您遇到新的 Android 特有问题，请在 GitHub 上提交 issue，并提供：

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