Hermes Agent 安装最简流程：Linux、macOS、WSL2 与 Termux 四端一次说清

Hermes Agent 是 Nous Research 推出的开源自学习个人 AI agent，GitHub 收获 118k+ stars，由 Hermes-3 模型团队同源开发。与 Claude Code、Codex、OpenCode 等编码专用工具不同，Hermes Agent 定位为”会成长的个人 agent”——它通过闭环学习循环自动从经验中创建可复用的技能（Skills），跨会话记忆用户偏好，通过 Telegram、Discord、Slack、WhatsApp、Signal 等多个通讯平台接入用户日常生活，并支持自然语言定时任务（cron）。

Hermes Agent 安装的最大特点是仅通过单一 install.sh 脚本分发——没有 npm、Homebrew、winget 包，所有平台共用同一条命令。支持 Linux、macOS、WSL2 与 Android Termux，不支持原生 Windows。本指南整理四端在不同设备上的最简安装流程，覆盖 Docker、SSH、Modal、Daytona 等六种执行后端的配置策略，以及从 OpenClaw 迁移的完整路径。

Hermes Agent 是什么：与编码 agent 的根本差异

理解 Hermes Agent 安装路径的设计选择，需要先搞清楚它的产品定位。Hermes 不是 Claude Code、Codex、OpenCode 那种”在终端里帮你写代码的 agent”，而是更接近”个人 AI 管家”——它的设计目标是持久运行、跨会话学习、跨平台触达：

• 自学习闭环：完成复杂任务后自动生成 Markdown 格式的 Skill 文档存入技能库，下次遇到类似任务先搜索已有技能而非从零推导。据 TokenMix.ai 的评测，积累 20+ 自创技能后，相似任务完成时间约缩短 40%
• 跨平台 gateway：通过单一 gateway 进程接入 Telegram、Discord、Slack、WhatsApp、Signal、Email 与 CLI，从手机给云端 VPS 上的 Hermes 发消息也能完成任务
• 三层持久记忆：FTS5 全文搜索 + LLM 摘要的会话历史检索、Honcho 用户建模、agentskills.io 标准的技能持久化
• 自然语言 cron：内置定时调度器，支持”每天早 8 点把昨日 GitHub 通知发到 Telegram”这类自然语言任务
• 六种 terminal backend：本地、Docker、SSH、Daytona、Singularity、Modal——agent 实际执行命令的环境与 Hermes 本体可分离

什么场景适合 Hermes：希望 7×24 运行在 VPS 或 home lab 上的个人 agent、需要从 Telegram 远程指挥的工作流、有跨会话用户记忆需求的研究工作、想要从 OpenClaw 迁移并保留所有技能与 API Key。

什么场景不适合：纯命令行编码、不想维护 Linux/Mac 环境的 Windows 原生用户、不希望 agent 自动生成”持久状态”的临时使用场景。

系统要求与前置检查

根据 Hermes Agent 官方文档：

• 操作系统：Linux、macOS、WSL2 或 Android（通过 Termux）
• 不支持原生 Windows：官方明确说明 Hermes 不支持 Windows 原生路径，Windows 用户必须先安装 WSL2
• Python：要求 Python 3.11，由安装脚本通过 uv 自动管理，无需手动安装
• Node.js：v22，由安装脚本自动安装（用于 WhatsApp bridge 与浏览器自动化）
• Git：唯一需要预先安装的依赖
• 硬件：2 GB RAM 起步，本地跑模型时需更多。运行 Hermes 本体仅 ~1 GB 磁盘
• 账号：Hermes 本体免费开源（MIT 协议），使用成本取决于模型 provider——可使用 Nous Portal、OpenRouter、NVIDIA NIM、智谱 GLM、Kimi、MiniMax、本地 Ollama 或 OpenAI/Anthropic 等任意 provider
• 网络：托管模型 API 需稳定网络。本地模型通过 OpenAI 兼容端点可离线运行

检查当前是否已安装：

hermes --version

如果返回版本号（当前最新版 v0.11.0，发布于 2026 年 4 月 23 日），说明已安装。否则按下文方法安装。

安装方法

方法一：官方安装脚本（所有平台推荐）

Hermes Agent 官方仅通过 install.sh 脚本分发——没有 npm 包、没有 Homebrew cask、没有 winget。所有平台共用同一条命令：

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

脚本自动处理：

• 使用 uv 安装 Python 3.11 与虚拟环境
• 安装 Node.js v22（用于 WhatsApp bridge）
• 安装 ripgrep、ffmpeg 等系统依赖
• 从 GitHub clone 仓库到 ~/.hermes/，建立 Python 虚拟环境
• 把 hermes 命令链接到 ~/.local/bin/hermes

完成后重载 shell：

source ~/.bashrc    # 或 source ~/.zshrc

运行 hermes –version 验证，运行 hermes 启动 TUI。

检测平台自动选择 extras：脚本会根据运行环境选择不同的 Python extras。Linux/macOS/WSL2 安装 .[all]（包含全部依赖与语音模式），Termux 安装 .[termux]（移除 Android 不兼容的语音相关库）。

方法二：Linux 与 macOS 部署细节

最常见的部署场景，按顺序执行：

# 安装 git（如未安装）
sudo apt install git              # Ubuntu / Debian
sudo dnf install git              # Fedora / RHEL
brew install git                  # macOS
 
# 运行官方安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 
# 重载 shell
source ~/.bashrc                  # bash
source ~/.zshrc                   # zsh
 
# 启动 setup 向导（一次性配置 model provider、tools、gateway）
hermes setup

setup 向导会按顺序问以下问题：

• Model provider：从 Nous Portal、OpenRouter、Anthropic、OpenAI、本地 Ollama 等中选择
• API Key：对应 provider 的 Key，存入 ~/.hermes/.env
• Terminal backend：默认 local，后续可改 Docker / SSH / Modal 等
• Gateway 平台：可选，如配 Telegram bot token、Discord 等
• Tools 与 skills：选择启用哪些工具与初始技能

完成后执行 hermes 进入 TUI，或 hermes –tui 进入更现代的 TUI（推荐）。

方法三：Windows 用户必须使用 WSL2

Hermes Agent 不支持 Windows 原生路径，根据官方文档说明，Windows 用户必须先安装 WSL2：

# 在 PowerShell 管理员窗口执行
wsl --install -d Ubuntu
 
# 重启电脑后进入 WSL Ubuntu，执行官方安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 
# 重载 shell
source ~/.bashrc

WSL2 安装注意事项：

• 所有依赖（Python、Node.js、git、ripgrep）必须在 WSL2 内安装，不要混用 Windows 原生侧的工具链
• 项目代码建议存储在 WSL2 文件系统（~/projects），不要放在 /mnt/c/ 下——后者跨文件系统访问性能差
• Hermes 默认启动会监听 localhost 端口（如 8642 给 gateway 用），WSL2 与 Windows 主机端口共享，可在 Windows 浏览器直接访问

方法四：Android Termux 移动端部署

Hermes Agent 是少数支持 Android 部署的 AI agent之一，对希望在手机上运行个人 agent 的用户尤其友好：

第一步：安装 Termux

不要从 Google Play 安装 Termux（已停止更新）。从 F-Droid 下载安装最新版本。

第二步：在 Termux 中运行安装脚本

# 更新 Termux 包索引
pkg update && pkg upgrade
 
# 安装基础依赖
pkg install git python
 
# 运行官方安装脚本（脚本会自动检测 Termux 并切换到 Android 流程）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Termux 路径的限制：根据官方 README，Termux 上 Hermes 安装的是 .[termux] extras 而非 .[all]，移除了 Android 不兼容的语音相关依赖（如 faster-whisper 的语音转文本功能）。其他 40+ 工具与跨会话记忆全部可用。

典型 Termux 使用场景：在手机上跑一个轻量 Hermes 实例，配置 Telegram gateway，把手机 24 小时挂在桌面充电——一个零成本的”随身 AI 助手”。结合 Termux 的 SSH 服务器功能，还可以从笔记本通过 SSH 远程操作手机上的 Hermes。

方法五：Docker 部署（生产环境推荐）

Docker 部署的优势是隔离性、可复制部署、配合 docker-compose 实现服务级管理。Hermes 提供官方 Docker 镜像 nousresearch/hermes-agent。

首次运行（交互式 setup）：

# 创建数据目录
mkdir -p ~/.hermes
 
# 交互式运行 setup 向导
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

setup 向导会引导配置 model provider、API Key 等，所有配置写入挂载的 ~/.hermes/.env。

持久化运行 gateway（推荐生产部署方式）：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

端口 8642 暴露 gateway 的 OpenAI 兼容 API 与健康检查端点。如果只用 Telegram/Discord 等聊天平台触达，该端口可不映射。

升级 Docker 部署：

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

数据目录 ~/.hermes 不受重建容器影响，技能、记忆、会话历史全部保留。

重要：UID 不匹配问题：容器内默认以 UID 10000 的 hermes 用户运行。若主机 ~/.hermes/ 归不同 UID 所有，会出现权限错误。解决方案是设置 HERMES_UID 与 HERMES_GID 环境变量匹配主机用户：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -e HERMES_UID=$(id -u) \
  -e HERMES_GID=$(id -g) \
  nousresearch/hermes-agent gateway run

方法六：克隆仓库手动安装（开发者）

适合想要修改源码、贡献 PR 或运行 dev 分支的开发者：

# 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
 
# 使用项目自带的 setup 脚本（自动安装 uv、创建虚拟环境）
./setup-hermes.sh
 
# 或手动等价步骤
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"
 
# 运行测试
scripts/run_tests.sh
 
# 启动（项目目录下的 hermes 会自动检测 venv）
./hermes

setup-hermes.sh 与 install.sh 的区别：

• install.sh（curl 安装）：面向最终用户，把仓库 clone 到 ~/.hermes/、链接全局 hermes 命令、启动 setup 向导
• setup-hermes.sh（仓库内）：面向贡献者，在当前 clone 目录建立开发环境、安装 dev 依赖

认证与 model provider 配置

与 Claude Code、Codex 不同，Hermes 不内置任何模型订阅，安装后必须至少配置一个 provider 才能开始使用。Hermes 支持的 provider 列表非常长：

• Nous Portal：Nous Research 自营服务，提供 Hermes-3 等开源模型，据 Decrypt 报道 v0.11.0 起 MiMo v2 Pro 对 Hermes 用户免费
• OpenRouter：聚合 200+ 模型，单 Key 访问，国内开发者常用入口
• NVIDIA NIM：Nemotron 模型族
• Xiaomi MiMo：小米开源 MiMo 模型
• z.ai / GLM：智谱 GLM 系列
• Kimi / Moonshot：月之暗面 Kimi
• MiniMax：MiniMax 模型
• Hugging Face：HF Inference API
• OpenAI / Anthropic：标准 GPT / Claude API
• 本地 Ollama：通过 OpenAI 兼容端点访问，零费用
• 自定义 OpenAI 兼容端点：任意第三方 OpenAI-compatible API

配置方法：

# 交互式选择 provider 与模型
hermes model
 
# 命令行设置默认模型
hermes config set model anthropic/claude-opus-4.6
 
# 设置 API Key
hermes config set OPENROUTER_API_KEY sk-or-...

切换模型不需重启：在 TUI 内执行 /model 即可热切换，会话历史不丢失。

Terminal Backend 选择：agent 在哪里执行命令

Hermes 一个独特设计是把 agent 本体与 agent 实际执行 shell 命令的环境分离。安装在你笔记本的 Hermes 可以让 agent 在远程 VPS 上执行命令，或在 Modal 云沙箱中运行。共有六种 backend：

• local：默认，在 Hermes 所在机器执行命令。适合个人开发与受信任环境
• docker：在本机 Docker 容器内执行，提供隔离。需 docker version 验证可用
• ssh：通过 SSH 在远程主机执行。需配置 TERMINAL_SSH_HOST 与 TERMINAL_SSH_USER
• modal：Modal 云端 serverless 沙箱，idle 时几乎零成本，按需启动。需 MODAL_TOKEN_ID
• daytona：Daytona 临时开发环境，类似 GitHub Codespaces。需 DAYTONA_API_KEY
• singularity：HPC 集群常用的 Singularity/Apptainer 容器。需 apptainer 或 singularity 在 PATH 中

切换 backend：

# 切到 Docker 隔离
hermes config set terminal.backend docker
 
# 切到远程 SSH
hermes config set terminal.backend ssh
 
# 切回本地
hermes config set terminal.backend local

选哪个 backend：

• 个人开发与学习：local（默认）即可
• 对 agent 自主写代码、运行命令存疑：docker，提供隔离防止误操作
• 已有云端 VPS 想 agent 在那里跑：ssh
• 追求极致 idle 成本：modal，闲置时几乎零成本

从 OpenClaw 迁移：自动化导入完整流程

Hermes 内置 hermes claw migrate 命令，自动从 ~/.openclaw 迁移配置、记忆、技能与 API Key——这对从 OpenClaw 切换过来的用户是杀手级特性。

首次 setup 自动检测：执行 hermes setup 时，向导会检测 ~/.openclaw 目录存在，自动询问是否迁移。

安装后手动迁移：

# 交互式完整迁移（默认 preset）
hermes claw migrate
 
# 预览将要迁移哪些内容（不实际执行）
hermes claw migrate --dry-run
 
# 仅迁移用户数据，不带 API Key 等敏感信息
hermes claw migrate --preset user-data
 
# 强制覆盖已存在的同名配置
hermes claw migrate --overwrite

迁移涵盖内容：

• SOUL.md：persona 定义文件
• Memories：MEMORY.md 与 USER.md 条目
• Skills：用户自创技能 → ~/.hermes/skills/openclaw-imports/
• 命令允许列表：approval patterns
• Messaging 配置：平台 token、允许用户列表、工作目录
• API Key 白名单：Telegram、OpenRouter、OpenAI、Anthropic、ElevenLabs 等
• TTS 资源：工作区音频文件
• AGENTS.md：通过 –workspace-target 指定项目级工作区指令

并行运行策略：迁移过程中可同时保留 OpenClaw 与 Hermes 在不同账号上运行——比如 OpenClaw 接 WeChat、Hermes 接 Telegram，等 Hermes 在 cron 与路由行为上完全匹配后再切换。社区项目 HermesClaw 提供 WeChat bridge，让两者可以在同一个微信账号上并存。

Gateway 配置：让 Hermes 出现在你的聊天软件

Hermes 的核心卖点之一是通过单一 gateway 进程接入多个聊天平台。安装后启用 gateway：

# 交互式 gateway setup 向导
hermes gateway setup
 
# 启动 gateway
hermes gateway start
 
# 安装为系统服务（systemd）以实现 7×24 运行
hermes gateway install

支持的聊天平台：

• Telegram：通过 BotFather 创建 bot 获取 token，配置到 gateway
• Discord：创建 Discord application bot 并邀请到服务器
• Slack：创建 Slack App 并安装到 workspace
• WhatsApp：通过 baileys 库（基于 Node.js）连接 WhatsApp Web
• Signal：通过 signal-cli 桥接
• Email：IMAP/SMTP 接收发送邮件

典型部署模式：在 5 美元/月的 VPS 上跑 gateway，配置 Telegram bot——出门在外通过手机 Telegram 给 bot 发”帮我把昨天的 GitHub 通知整理成日报”，VPS 上的 Hermes 处理后回复结果。这是 Hermes 与传统编码 agent 最大的体验差异。

更新方式

Hermes 提供内置升级命令：

# 升级到最新版本
hermes update

由于 Hermes 通过 git clone 安装而非包管理器分发，升级实际是：

• git pull 最新 main 分支代码
• uv pip install 更新依赖
• 迁移配置文件（如有 schema 变更）

Docker 部署的升级：拉取最新镜像后重建容器（前面方法五已说明）。

Termux 上的升级：执行 hermes update，注意 Termux 内升级时间较长，可能需要 5-10 分钟。

常见问题排查

问题 1：安装脚本失败 – Python 3.11 找不到

原因：安装脚本用 uv 自动安装 Python 3.11，但某些受限环境（如学校机房、企业 NAT）可能阻断 uv 的下载。

解决方案：先手动安装 uv，再执行 install.sh：

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

或参考方法六手动 clone 仓库的路径，所有依赖都通过本地 uv 处理。

问题 2：hermes 命令安装后找不到

原因：PATH 中未包含 ~/.local/bin。

解决方案：

# 检查 PATH
echo $PATH | tr ':' '\n' | grep local/bin
 
# 加入 PATH（bash）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
 
# zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

问题 3：hermes doctor 报错

解决方案：hermes doctor 是诊断工具，报错通常会指出具体哪个组件出问题——Python 版本、Node 版本、缺失的系统依赖（ripgrep/ffmpeg）、Docker 不可用等。按提示逐一修复，必要时重新执行 install.sh。

问题 4：Termux 上 voice 相关功能失败

原因：Termux 上 Hermes 默认装 .[termux] extras，不包含语音转文本与语音合成依赖（faster-whisper 等库不兼容 Android）。

解决方案：这是预期限制，不要尝试在 Termux 上启用语音模式。其他 40+ 工具与跨会话记忆全部可用。

问题 5：Docker 部署 UID 权限错误

原因：容器内 hermes 用户 UID=10000，与主机 ~/.hermes/ 目录所有者 UID 不匹配。

解决方案：通过环境变量传递主机 UID：

docker run -d \
  --name hermes \
  -v ~/.hermes:/opt/data \
  -e HERMES_UID=$(id -u) \
  -e HERMES_GID=$(id -g) \
  nousresearch/hermes-agent gateway run

问题 6：从 OpenClaw 迁移后某些技能不工作

原因：OpenClaw 与 Hermes 的技能格式略有差异，自动迁移会处理大部分情况但不保证 100% 兼容。

解决方案：

• 先用 hermes claw migrate –dry-run 预览将迁移的内容
• 迁移后在 ~/.hermes/skills/openclaw-imports/ 检查导入的 skill 文档
• 不工作的技能可手动调整或在 Skills Hub 找替代版本

问题 7：gateway 接 Telegram 但收不到消息

解决方案：

• 检查 BotFather 给的 token 是否正确写入 ~/.hermes/.env
• 确保 bot 已启动（hermes gateway start）且日志无错误
• 在 BotFather 设置 bot 的 /setprivacy 为 Disable，否则 bot 在群聊中收不到消息
• 初次发消息前需先在 Telegram 中搜索 bot 用户名并点击 Start

问题 8：国内网络无法访问 Anthropic / OpenAI / Nous Portal

解决方案：

• 设置代理：export HTTPS_PROXY=http://proxy.example.com:port 后重启 hermes
• 使用 OpenRouter（部分国内可达）或国内 provider（智谱 GLM、Kimi、MiniMax 等）
• 本地 Ollama + 开源模型，完全离线运行

问题 9：Modal backend 提示认证失败

解决方案：

# 安装 modal SDK
pip install modal
 
# 通过浏览器授权
modal token new
 
# 验证
hermes doctor

成功后 ~/.modal.toml 会写入 token，Hermes 自动读取。

问题 10：自学习闭环没看到效果

原因：Hermes 的 skill 创建是在完成复杂任务后触发，简单的单步对话不会生成新 skill。

解决方案：

• 给 Hermes 一些有完整流程的复杂任务（如”帮我配置一个 GitHub Actions 工作流并提交 PR”）
• 检查 ~/.hermes/skills/ 是否有自创 skill 文档生成
• 在 TUI 内执行 /skills 浏览已有技能库

验证安装与基础使用

# 检查版本
hermes --version
 
# 完整诊断
hermes doctor
 
# 启动 TUI（推荐）
hermes --tui
 
# 经典 CLI 模式
hermes

进入 Hermes 后可使用以下内置命令：

# 切换 model 与 provider
/model [provider:model]
 
# 设置 personality
/personality [name]
 
# 重新开始会话
/new
/reset
 
# 浏览 skills
/skills
 
# 触发特定 skill
/
 
# 压缩对话历史
/compress
 
# 查看 token 用量
/usage
 
# 撤销 / 重做
/undo
/retry

装完之后的关键三步：

• 用一个具体的小任务验证基础对话能跑通——官方建议先确认普通聊天工作，再加 gateway、cron、skills、voice 等高级功能
• 配置一个聊天平台 gateway（推荐先 Telegram，最简单），让 Hermes 跨设备触达
• 给一个完整的工作流任务（如”分析这个项目并生成开发文档”），观察 ~/.hermes/skills/ 是否生成自创 skill——这是 Hermes 与其他 agent 的核心差异

卸载方式

Hermes 安装通过 git clone + venv，没有包管理器分发，卸载需手动清理：

# 删除 hermes 命令链接
rm -f ~/.local/bin/hermes
 
# 删除主目录（包含代码、虚拟环境、配置、数据、技能、记忆）
rm -rf ~/.hermes
 
# Docker 部署的卸载
docker rm -f hermes
docker rmi nousresearch/hermes-agent
rm -rf ~/.hermes
 
# 项目克隆方式安装的卸载
rm -rf /path/to/hermes-agent

注意安全：~/.hermes/.env 包含所有 provider 的 API Key 明文，Telegram bot token 等敏感信息。卸载前如不打算重装，建议先撤销相关 Key。

~/.hermes 目录结构：

• ~/.hermes/.env：API Key 与配置
• ~/.hermes/skills/：技能库（含自创技能）
• ~/.hermes/sessions/：会话历史（FTS5 全文搜索数据库）
• ~/.hermes/memory/：跨会话持久记忆
• ~/.hermes/cache/：远程同步缓存（SSH/Modal/Daytona backend 用）

获取方式

GitHub 仓库：NousResearch/hermes-agent

官方文档：Hermes Agent Docs

快速开始：Quickstart Guide

Termux 详细指南：Termux Guide

CLI 命令参考：CLI Reference

环境变量参考：Environment Variables

Skills Hub：agentskills.io

社区 Discord：Nous Research Discord

精选资源列表：awesome-hermes-agent

Hermes Agent 与 Claude Code、Codex、OpenCode 的产品定位完全不同——它不是编码工具，而是面向”个人 AI 管家”场景的自学习 agent，覆盖跨平台触达、跨会话记忆、自然语言定时任务等编码 agent 不涉及的能力。但安装本身只是入口，真正决定 Hermes 价值的是后续SOUL.md persona 设计、技能库的持续积累、gateway 多平台路由配置以及 backend 选择策略。对中文开发者而言，Hermes 与 Claude Code 等编码 agent 是互补关系——Claude Code 解决”如何更好地写代码”，Hermes 解决”如何让 AI 在你的日常生活与工作流中持续提供价值”。