跳到主要内容

Android / Termux

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

它能让你在手机上获得可用的本地 CLI，以及目前已确认能在 Android 上顺利安装的核心 extra。

已验证路径支持什么？​

已验证的 Termux bundle 会安装：

  • Hermes CLI
  • cron 支持
  • PTY / 后台终端支持
  • Telegram 网关支持（手动 / 尽力而为的后台运行）
  • MCP 支持
  • Honcho memory 支持
  • ACP 支持

对应的安装命令是：

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

哪些还不在已验证路径内？​

有些功能仍依赖桌面 / 服务器风格的依赖项，这些依赖尚未发布到 Android，或还没有在手机上验证：

  • .[all] 目前不支持 Android
  • voice extra 受 faster-whisper -> ctranslate2 限制，而 ctranslate2 没有发布 Android wheel
  • Termux 安装器会跳过自动浏览器 / Playwright 引导流程
  • Termux 内无法使用基于 Docker 的终端隔离
  • 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 创建 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 — 运行时和 venv 支持
  • 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 对 jiter 这类基于 Rust / maturin 的包很重要。

4. 安装经过验证的 Termux bundle​

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 中，因此这样做之后，新的 shell 会话也能直接使用 hermes，不用每次都重新激活 venv。

6. 验证安装​

hermes version
hermes doctor

7. 启动 Hermes​

hermes

推荐的后续设置​

配置模型​

hermes model

或者直接把密钥写入 ~/.hermes/.env。

之后重新运行完整交互式向导​

hermes setup

手动安装可选的 Node 依赖​

已验证的 Termux 路径会有意跳过 Node / 浏览器引导流程。如果你之后想自己尝试浏览器工具：

pkg install nodejs-lts
npm install

浏览器工具会自动把 Termux 目录（/data/data/com.termux/files/usr/bin）加入 PATH 搜索，因此无需额外配置 PATH，也能发现 agent-browser 和 npx。

在有正式文档说明之前，请把 Android 上的浏览器 / WhatsApp 工具视为实验性功能。

故障排除​

安装 .[all] 时出现 No solution found​

请改用经过验证的 Termux bundle：

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

当前的阻塞点是 voice extra：

  • voice 会拉入 faster-whisper
  • faster-whisper 依赖 ctranslate2
  • ctranslate2 没有发布 Android wheel

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 level：

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 backend 不可用
  • 在已验证路径中，faster-whisper 的本地语音转写不可用
  • 安装器会有意跳过浏览器自动化设置
  • 某些可选 extra 也许能工作，但目前只有 .[termux] 被正式记录为经过验证的 Android bundle

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

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