安装

使用一键安装程序在两分钟内启动 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 轮子构建
• 通过 pip 安装经过精选的 .[termux] 额外组件
• 默认跳过未经测试的浏览器 / WhatsApp 启动流程

如需完全显式路径，请参考专用的 Termux 指南。

Windows

原生 Windows 不支持。请安装 WSL2，并在其中运行 Hermes Agent。上述安装命令在 WSL2 内部同样适用。

安装程序执行的操作

安装程序会自动处理所有事项 —— 所有依赖项（Python、Node.js、ripgrep、ffmpeg）、仓库克隆、虚拟环境创建、全局 hermes 命令设置以及 LLM 提供商配置。完成后，您即可开始聊天。

安装后操作

重新加载您的 shell 并开始聊天：

source ~/.bashrc   # or: source ~/.zshrc
hermes             # Start chatting!

如需后续重新配置个别设置，请使用专用命令：

hermes model          # Choose your LLM provider and model
hermes tools          # Configure which tools are enabled
hermes gateway setup  # Set up messaging platforms
hermes config set     # Set individual config values
hermes setup          # Or run the full setup wizard to configure everything at once

---

先决条件

唯一必需的先决条件是 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 设置 指南。

---

手动安装

如果您希望对安装过程拥有完全控制，请遵循以下步骤。

步骤 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 并创建虚拟环境

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv with Python 3.11 (uv downloads it if not present — no sudo needed)
uv venv venv --python 3.11

提示

您无需激活虚拟环境即可使用 hermes。入口点已硬编码指向虚拟环境的 Python，因此一旦创建符号链接，即可全局使用。

步骤 3：安装 Python 依赖项

# Tell uv which venv to install into
export VIRTUAL_ENV="$(pwd)/venv"

# Install with all extras
uv pip install -e ".[all]"

如果您仅需要核心代理（无 Telegram/Discord/cron 支持）：

uv pip install -e "."

可选额外组件说明

额外组件	添加内容	安装命令
all	以下所有内容	uv pip install -e ".[all]"
messaging	Telegram 与 Discord 网关	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	模型上下文协议支持	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，而 faster-whisper 依赖 ctranslate2 轮子，这些轮子尚未发布到 Android。请使用 .[termux] 获取经过测试的移动端安装路径，然后按需添加个别额外组件。

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

# RL training backend (optional)
uv pip install -e "./tinker-atropos"

两者均为可选 —— 如果跳过，相应工具集将不可用。

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

仅在需要 浏览器自动化（Browserbase 驱动）和 WhatsApp 桥接 时才需要：

npm install

步骤 6：创建配置目录

# Create the directory structure
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}

# Copy the example config file
cp cli-config.yaml.example ~/.hermes/config.yaml

# Create an empty .env file for API keys
touch ~/.hermes/.env

第 7 步：添加您的 API 密钥

打开 ~/.hermes/.env 文件，并至少添加一个 LLM 提供商的密钥：

# Required — at least one LLM provider:
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# Optional — enable additional tools:
FIRECRAWL_API_KEY=fc-your-key          # Web search & scraping (or self-host, see docs)
FAL_KEY=your-fal-key                   # Image generation (FLUX)

或者通过 CLI 设置：

hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-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 步：配置您的提供方

hermes model       # Select your LLM provider and model

第 10 步：验证安装

hermes version    # Check that the command is available
hermes doctor     # Run diagnostics to verify everything is working
hermes status     # Check your configuration
hermes chat -q "Hello! What tools do you have available?"

---

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

适用于只想获取命令的用户：

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

# Clone & enter
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# Create venv with Python 3.11
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# Install everything
uv pip install -e ".[all]"
uv pip install -e "./tinker-atropos"
npm install  # optional, for browser tools and WhatsApp

# Configure
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=sk-or-v1-your-key' >> ~/.hermes/.env

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

# Verify
hermes doctor
hermes

---

故障排除

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

如需更多诊断信息，请运行 hermes doctor —— 它将明确告知您缺少什么以及如何修复。