安装指南 (Installation)

> 📖 本文档翻译自 Hermes Agent 官方文档 > 最后更新：2026-04-16

通过一行安装命令，不到两分钟即可让 Hermes Agent 运行起来；或者按照手动步骤获得完全控制。

快速安装

Linux / macOS / WSL2

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

Android / Termux

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

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

安装程序会自动检测 Termux 并切换到经过测试的 Android 安装流程：

• 使用 Termux 的 pkg 安装系统依赖（git、python、nodejs、ripgrep、ffmpeg、构建工具）
• 使用 python -m venv 创建虚拟环境
• 自动导出 ANDROID_API_LEVEL 以支持 Android Wheel 构建
• 使用 pip 安装精选的 .[termux] 扩展组件
• 默认跳过未经测试的浏览器 / WhatsApp 引导

如果你希望完全手动的路径，请参阅专门的 Termux 指南。

> ⚠️ Windows 用户： 原生 Windows 不受支持。请安装 WSL2 并在 WSL2 中运行 Hermes Agent。上面的安装命令在 WSL2 内可以正常工作。

安装程序做了什么

安装程序自动处理所有事情——所有依赖（Python、Node.js、ripgrep、ffmpeg）、仓库克隆、虚拟环境、全局 hermes 命令设置以及 LLM Provider 配置。安装完成后即可开始对话。

安装后

重新加载你的 Shell，然后开始对话：

source ~/.bashrc   # 或: source ~/.zshrc
hermes             # 开始对话！

之后如需重新配置各项设置，可使用专用命令：

hermes model          # 选择你的 LLM Provider 和模型
hermes tools          # 配置启用的工具
hermes gateway setup  # 设置消息平台
hermes config set     # 设置单个配置项
hermes setup          # 或运行完整设置向导一次性配置所有内容

前置条件

唯一的前置条件是 Git。安装程序会自动处理其他所有内容：

• uv（高速 Python 包管理器）
• Python 3.11（通过 uv 安装，无需 sudo）
• Node.js v22（用于浏览器自动化和 WhatsApp 桥接）
• ripgrep（快速文件搜索）
• ffmpeg（TTS 的音频格式转换）

> ℹ️ 你不需要手动安装 Python、Node.js、ripgrep 或 ffmpeg。安装程序会检测缺失的组件并自动安装。只需确保 git 可用（git --version）。

Nix 用户

如果你使用 Nix（在 NixOS、macOS 或 Linux 上），有专门的配置路径，包括 Nix Flake、声明式 NixOS 模块和可选的容器模式。详见 Nix & NixOS Setup 指南。

手动安装

如果你希望完全控制安装过程，请按以下步骤操作。

步骤 1：克隆仓库

使用 --recurse-submodules 克隆以拉取所需的子模块：

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

如果你已经克隆但没有 --recurse-submodules：

git submodule update --init --recursive

步骤 2：安装 uv 并创建虚拟环境

# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用 Python 3.11 创建虚拟环境（uv 会自动下载，无需 sudo）
uv venv venv --python 3.11

> 💡 提示： 你不需要激活虚拟环境来使用 hermes。入口点有硬编码的 shebang 指向虚拟环境中的 Python，因此符号链接后即可全局使用。

步骤 3：安装 Python 依赖

# 告诉 uv 要安装到哪个虚拟环境
export VIRTUAL_ENV="$(pwd)/venv"

# 安装所有扩展组件
uv pip install -e ".[all]"

如果你只需要核心 Agent（不需要 Telegram/Discord/Cron 支持）：

uv pip install -e "."

可选扩展组件一览

扩展	添加的功能	安装命令
all	以下所有内容	uv pip install -e ".[all]"
messaging	Telegram、Discord 和 Slack Gateway	uv pip install -e ".[messaging]"
cron	用于定时任务的 Cron 表达式解析	uv pip install -e ".[cron]"
cli	设置向导的终端菜单 UI	uv pip install -e ".[cli]"
modal	Modal 云执行后端	uv pip install -e ".[modal]"
tts-premium	ElevenLabs 高品质语音	uv pip install -e ".[tts-premium]"
voice	CLI 麦克风输入 + 音频播放	uv pip install -e ".[voice]"
pty	PTY 终端支持	uv pip install -e ".[pty]"
termux	经过测试的 Android / Termux 打包（cron、cli、pty、mcp、honcho、acp）	python -m pip install -e ".[termux]" -c constraints-termux.txt
honcho	AI 原生记忆（Honcho 集成）	uv pip install -e ".[honcho]"
mcp	Model Context Protocol 支持	uv pip install -e ".[mcp]"
homeassistant	Home Assistant 集成	uv pip install -e ".[homeassistant]"
acp	ACP 编辑器集成支持	uv pip install -e ".[acp]"
slack	Slack 消息	uv pip install -e ".[slack]"
dev	pytest 和测试工具	uv pip install -e ".[dev]"

你可以组合多个扩展：uv pip install -e ".[messaging,cron]"

> ⚠️ Termux 用户： .[all] 目前在 Android 上不可用，因为 voice 扩展依赖 faster-whisper，而后者依赖的 ctranslate2 没有发布 Android Wheel。请使用 .[termux] 作为经过测试的移动端安装路径，然后根据需要单独添加扩展。

步骤 4：安装可选子模块（如需要）

# RL 训练后端（可选）
uv pip install -e "./tinker-atropos"

两者都是可选的——如果你跳过它们，对应的 Toolset 简单地不可用而已。

步骤 5：安装 Node.js 依赖（可选）

仅在使用浏览器自动化（基于 Browserbase）和 WhatsApp 桥接时需要：

npm install

步骤 6：创建配置目录

# 创建目录结构
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}

# 复制示例配置文件
cp cli-config.yaml.example ~/.hermes/config.yaml

# 创建空的 .env 文件用于存放 API Key
touch ~/.hermes/.env

步骤 7：添加你的 API Key

打开 ~/.hermes/.env，至少添加一个 LLM Provider 的 Key：

# 必填 — 至少一个 LLM Provider：
OPENROUTER_API_KEY=***

# 可选 — 启用额外工具：
FIRECRAWL_API_KEY=***              # Web 搜索和爬取（也可自托管，见文档）
FAL_KEY=your-fal-key               # 图像生成（FLUX）

或者通过 CLI 设置：

hermes config set OPENROUTER_API_KEY sk-or-...here

步骤 8：将 hermes 添加到 PATH

mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

如果 ~/.local/bin 不在你的 PATH 中，添加到你的 Shell 配置：

# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# Fish
fish_add_path $HOME/.local/bin

步骤 9：配置 Provider

hermes model       # 选择你的 LLM Provider 和模型

步骤 10：验证安装

hermes version    # 检查命令是否可用
hermes doctor     # 运行诊断，验证一切正常
hermes status     # 检查你的配置
hermes chat -q "Hello! What tools do you have available?"

快速参考：手动安装（精简版）

只想要命令的人：

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆并进入
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 使用 Python 3.11 创建虚拟环境
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# 安装所有内容
uv pip install -e ".[all]"
uv pip install -e "./tinker-atropos"
npm install  # 可选，用于浏览器工具和 WhatsApp

# 配置
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env
echo 'OPENROUTER_API_KEY=***' >> ~/.hermes/.env

# 全局可用
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

# 验证
hermes doctor
hermes

故障排除

问题	解决方案
hermes: command not found	重新加载 Shell（source ~/.bashrc）或检查 PATH
API key not set	运行 hermes model 配置 Provider，或 hermes config set OPENROUTER_API_KEY your_key
更新后配置缺失	运行 hermes config check 然后 hermes config migrate

如需更多诊断，运行 hermes doctor——它会准确告诉你缺少什么以及如何修复。