安装

使用单行安装器，你可以在两分钟内让 Hermes Agent 运行起来；如果你希望完全掌控安装过程，也可以按照手动步骤进行安装。

快速安装

Linux / macOS / WSL2

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

Android / Termux

Hermes 现在也提供了可识别 Termux 的安装路径：

  1. 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 创建 virtualenv
  • 为 Android wheel 构建自动导出 ANDROID_API_LEVEL
  • 使用 pip 安装精心整理的 .[termux] 扩展包
  • 默认跳过尚未充分测试的 browser / WhatsApp bootstrap

如果你想使用完全显式的安装路径，请参考专门的 Termux guide。

原生 Windows 不受支持。请安装 WSL2，并在其中运行 Hermes Agent。上面的安装命令可直接在 WSL2 内使用。

安装器会做什么

安装器会自动处理所有内容——包括全部依赖项（Python、Node.js、ripgrep、ffmpeg）、仓库克隆、虚拟环境、全局 hermes 命令设置，以及 LLM provider 配置。安装完成后，你就可以立即开始对话。

安装完成后

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

  1. source ~/.bashrc   # 或：source ~/.zshrc
  2. hermes             # 开始聊天！

如果之后想重新配置某些单独设置，可以使用以下专用命令：

  1. hermes model          # 选择你的 LLM provider 和 model
  2. hermes tools          # 配置启用哪些工具
  3. hermes gateway setup  # 设置消息平台
  4. hermes config set     # 设置单独的配置项
  5. hermes setup          # 或运行完整的设置向导，一次性配置所有内容

前置要求

唯一的前置要求是 Git。其余一切都由安装器自动处理：

  • uv（高速 Python 包管理器）
  • Python 3.11（通过 uv 安装，无需 sudo）
  • Node.js v22（用于 browser automation 和 WhatsApp bridge）
  • ripgrep（高速文件搜索）
  • ffmpeg（用于 TTS 的音频格式转换）

:::tip Nix 用户 如果你使用 Nix（无论是在 NixOS、macOS 还是 Linux 上），这里有一条专门的安装路径，提供 Nix flake、声明式 NixOS module，以及可选的 container mode。请参阅 Nix & NixOS Setup 指南。 :::

手动安装

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

第 1 步：克隆仓库

使用 --recurse-submodules 进行克隆，以拉取所需的 submodules：

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

如果你之前克隆时没有使用 --recurse-submodules：

  1. git submodule update --init --recursive

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

  1. # 安装 uv（如果尚未安装）
  2. curl -LsSf https://astral.sh/uv/install.sh | sh
  4. # 使用 Python 3.11 创建 venv（如果本机没有，uv 会自动下载 —— 无需 sudo）
  5. uv venv venv --python 3.11

第 3 步：安装 Python 依赖

  1. # 告诉 uv 要安装到哪个 venv
  2. export VIRTUAL_ENV="$(pwd)/venv"
  4. # 安装所有扩展
  5. uv pip install -e ".[all]"

如果你只想安装核心 agent（不包含 Telegram / Discord / cron 支持）：

  1. uv pip install -e "."

可选扩展包说明

Extra 功能 安装命令
all 包含以下所有内容 uv pip install -e ".[all]"
messaging Telegram 与 Discord gateway uv pip install -e ".[messaging]"
cron 用于计划任务的 Cron expression 解析 uv pip install -e ".[cron]"
cli setup wizard 的终端菜单 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-native memory（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 editor 集成支持 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]"

:::tip Termux 用户 .[all] 目前在 Android 上不可用，因为 voice 扩展会拉取 faster-whisper，而它依赖的 ctranslate2 wheels 尚未发布 Android 版本。请使用 .[termux] 作为经过测试的移动端安装路径，然后按需单独添加其他扩展。 :::

第 4 步：安装可选 submodules（如有需要）

  1. # RL training backend（可选）
  2. uv pip install -e "./tinker-atropos"

这两项都是可选的——如果你跳过它们，对应的 toolsets 只是不会可用。

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

仅在需要 browser automation（基于 Browserbase）和 WhatsApp bridge 时才需要：

  1. npm install

第 6 步：创建配置目录

  1. # 创建目录结构
  2. mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
  4. # 复制示例配置文件
  5. cp cli-config.yaml.example ~/.hermes/config.yaml
  7. # 创建空的 .env 文件，用于保存 API keys
  8. touch ~/.hermes/.env

第 7 步：添加你的 API keys

打开 ~/.hermes/.env，至少添加一个 LLM provider key：

  1. # 必需 —— 至少提供一个 LLM provider：
  2. OPENROUTER_API_KEY=sk-or-v1-your-key-here
  4. # 可选 —— 启用额外工具：
  5. FIRECRAWL_API_KEY=fc-your-key          # Web search 与 scraping（也可自托管，参见文档）
  6. FAL_KEY=your-fal-key                   # 图像生成（FLUX）

你也可以通过 CLI 设置它们：

  1. hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here

第 8 步：将 hermes 添加到你的 PATH

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

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

  1. # Bash
  2. echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
  4. # Zsh
  5. echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
  7. # Fish
  8. fish_add_path $HOME/.local/bin

第 9 步：配置你的 Provider

  1. hermes model       # 选择你的 LLM provider 和 model

第 10 步：验证安装

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

速查版：手动安装（精简版）

适合只想看命令的人：

  1. # 安装 uv
  2. curl -LsSf https://astral.sh/uv/install.sh | sh
  4. # 克隆并进入目录
  5. git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
  6. cd hermes-agent
  8. # 使用 Python 3.11 创建 venv
  9. uv venv venv --python 3.11
  10. export VIRTUAL_ENV="$(pwd)/venv"
  12. # 安装全部内容
  13. uv pip install -e ".[all]"
  14. uv pip install -e "./tinker-atropos"
  15. npm install  # 可选，用于 browser tools 和 WhatsApp
  17. # 配置
  18. mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
  19. cp cli-config.yaml.example ~/.hermes/config.yaml
  20. touch ~/.hermes/.env
  21. echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env
  23. # 让 hermes 可全局使用
  24. mkdir -p ~/.local/bin
  25. ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
  27. # 验证
  28. hermes doctor
  29. 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