安装

你可以直接使用一键安装脚本，在两分钟左右启动 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）构建
• 安装精选的 .[termux] 扩展包，包含 pip
• 默认跳过未经测试的浏览器 / 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 的音频格式转换）

info

你不需要手动安装 Python、Node.js、ripgrep 或 ffmpeg。安装脚本会自动检测缺失项并完成安装。你只需要确认 git 可用即可，例如先运行一次 git --version。

Nix 用户

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

---

手动安装

如果你希望对安装过程拥有完全控制权，可以按下面的步骤手动安装。

第一步：克隆仓库

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

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

如果已克隆但未使用 --recurse-submodules：

git submodule update --init --recursive

第二步：安装 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

tip

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

第三步：安装 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 与 Slack 网关	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，而后者依赖于尚未发布 Android 版本的 ctranslate2 轮子。请使用 .[termux] 获取经测试的移动端安装路径，再根据需要逐步添加个别扩展。

第四步：安装可选子模块（如需）

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

这一步是可选的；如果跳过，对应工具集就不会启用。

第五步：安装 Node.js 依赖（可选）

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

npm install

第六步：创建配置目录

# 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

第七步：添加你的 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

第八步：将 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

第九步：配置你的提供商

hermes model       # Select your LLM provider and model

第十步：验证安装

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 —— 它会明确告诉你缺少什么以及如何修复。