Hermes Agent 完整安装教程

Hermes Agent 是由 NousResearch 开发的一款强大的 AI 代理工具，它能够帮助用户完成各种复杂任务，包括浏览器自动化、消息平台集成、文件处理等。本教程将详细介绍 Hermes Agent 的安装过程，无论您选择快速安装还是手动安装，都能找到适合自己的方案。

一、工具简介与核心特性

Hermes Agent 是一款基于大型语言模型的智能代理系统，其设计理念是让用户能够在两分钟内快速上手使用。通过简洁的命令行界面，用户可以与 AI 进行对话、配置各种工具、设置消息网关等。该工具的核心优势在于其高度模块化的架构，用户可以根据自己的需求选择性地安装不同的功能组件，从而避免不必要的依赖占用。

从技术架构角度来看，Hermes Agent 采用 Python 作为主要开发语言，配合 Node.js 实现浏览器自动化和 WhatsApp 桥接功能。它支持多种 LLM 提供商，包括 OpenRouter、Anthropic、OpenAI 等主流服务。工具层面，Hermes Agent 集成了文件搜索、网络搜索、图像生成、音频处理等实用功能，能够满足大多数日常和专业的 AI 辅助需求。

二、快速安装指南

对于希望快速开始使用的用户，Hermes Agent 提供了一键安装脚本，能够自动检测系统环境、安装所有必要依赖、配置虚拟环境，并设置全局命令。以下针对不同操作系统和平台详细说明安装步骤。

2.1 Linux、macOS 及 WSL2 环境安装

在 Linux 发行版、macOS 或 Windows Subsystem for Linux 2（WSL2）环境中，安装过程完全相同。打开终端，执行以下命令即可完成全部安装流程：

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

该安装脚本会自动完成以下操作：首先检测系统环境，识别缺失的依赖项；然后安装 uv（快速的 Python 包管理器）、Python 3.11、Node.js v22、ripgrep（高速文件搜索工具）和 ffmpeg（音视频格式转换工具）；接着克隆代码仓库并创建 Python 虚拟环境；最后配置全局 hermes 命令，使您能够在任何位置直接调用。

安装完成后，需要重新加载 shell 配置以使命令生效。执行以下命令刷新环境变量：

source ~/.bashrc   # 如果使用 Bash shell
source ~/.zshrc    # 如果使用 Zsh shell

刷新完成后，直接在终端输入 hermes 即可启动与 AI 的对话交互。

2.2 Android 与 Termux 环境安装

Hermes Agent 现在提供了专门的 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 专用指南。

2.3 Windows 系统注意事项

需要特别说明的是，Hermes Agent 目前不支持原生的 Windows 环境。微软官方强烈建议 Windows 用户安装 WSL2（Windows Subsystem for Linux 2），然后在 WSL2 环境中运行 Hermes Agent。所有前述的 Linux/macOS/WSL2 安装命令在 WSL2 环境中均可正常工作。

安装 WSL2 的步骤如下：打开 PowerShell（以管理员身份），执行 wsl --install 命令，然后按照提示重启计算机。安装完成后，您可以在开始菜单中找到 WSL 终端入口，进入后即可使用前述的快速安装命令。

三、安装前提条件详解

在开始安装之前，了解必要的环境依赖非常重要。虽然快速安装脚本会自动处理大部分依赖，但掌握这些信息有助于理解安装过程和后续的问题排查。

3.1 必需依赖项

唯一必须手动安装的依赖是 Git 版本控制系统。可以通过以下命令验证 Git 是否已安装：

git --version

如果命令返回版本号（如 git version 2.34.1），则说明 Git 已可用。如果提示命令未找到，需要先安装 Git：Ubuntu/Debian 系统使用 sudo apt install git，macOS 系统可以使用 Homebrew 执行 brew install git，或直接从 Git 官网下载安装包。

3.2 自动安装的依赖项

快速安装脚本会自动检测并安装以下依赖，用户无需手动操作：

依赖项	功能描述	备注
uv	极速 Python 包管理器	基于 Rust 开发，比 pip 快 10-100 倍
Python 3.11	编程语言环境	uv 会自动下载，无需 sudo 权限
Node.js v22	JavaScript 运行时	用于浏览器自动化和 WhatsApp 集成
ripgrep	高速文件搜索工具	递归搜索效率远超传统 grep
ffmpeg	音视频格式转换	TTS 语音合成的必需组件

这种设计大大降低了安装门槛，用户只需确保 Git 可用，其他一切由安装脚本处理。

3.3 Nix 用户特殊说明

如果您是 Nix/NixOS 用户（包括 NixOS、macOS 或 Linux 上的 Nix），官方提供了专门的设置路径，包括 Nix flake 声明式配置、NixOS 模块集成以及可选的容器模式。详细配置方法请参考官方的 Nix 与 NixOS 设置指南。

四、手动安装完整步骤

对于希望完全掌控安装过程、了解每个步骤细节的用户，以下提供详细的手动安装指南。每个步骤都经过详细说明，帮助您理解整个安装架构。

4.1 步骤一：克隆代码仓库

首先需要从 GitHub 克隆 Hermes Agent 的代码仓库。推荐使用 --recurse-submodules 参数，这样可以在克隆时一并拉取所有必需的子模块：

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

如果您之前已经克隆了仓库但没有添加子模块参数，可以通过以下命令补充拉取：

git submodule update --init --recursive

这一步非常重要，因为某些功能模块（如 tinker-atropos）是作为独立的子模块存在的，缺少它们会导致相应功能不可用。

4.2 步骤二：安装 uv 与创建虚拟环境

Hermes Agent 使用 uv 作为 Python 包管理器。uv 是一个用 Rust 编写的极速包管理工具，安装速度比传统 pip 快得多。首先安装 uv：

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

安装完成后，使用 uv 创建 Python 3.11 虚拟环境：

uv venv venv --python 3.11

uv 的一个重要特性是它会自动下载指定版本的 Python（如果系统中没有），整个过程无需 root 权限。创建的虚拟环境位于项目根目录的 venv 文件夹中。

4.3 步骤三：安装 Python 依赖包

设置虚拟环境变量，告诉 uv 在哪里安装包：

export VIRTUAL_ENV="$(pwd)/venv"

然后安装所有 Python 依赖。如果希望安装全部功能组件（包括 Telegram、Discord、Slack、cron 调度等），执行：

uv pip install -e ".[all]"

如果您只需要核心代理功能（不包含消息网关等），可以只安装基础包：

uv pip install -e "."

3.4 可选扩展包详解

Hermes Agent 采用了高度模块化的设计，用户可以根据实际需求选择性安装功能扩展。以下是各扩展包的详细说明：

扩展包名称	功能说明	安装命令
all	包含以下所有扩展	uv pip install -e ".[all]"
messaging	Telegram、Discord、Slack 消息网关	uv pip install -e ".[messaging]"
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	命令行麦克风输入和音频播放	uv pip install -e ".[voice]"
pty	PTY 终端支持	uv pip install -e ".[pty]"
termux	Android/Termux 专用包组合	python -m pip install -e ".[termux]" -c constraints-termux.txt
honcho	AI 原生记忆集成	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 用户特别提示：由于 voice 扩展依赖的 faster-whisper 包需要 ctranslate2 编译包，而该包目前没有发布 Android 平台版本，因此 .[all] 在 Android 上不可用。建议 Termux 用户使用 .[termux] 作为基础安装，然后按需添加其他扩展。

4.4 步骤四：安装可选子模块

Hermes Agent 还包含一些可选的子模块仓库，提供额外的功能支持。RL 训练后端是其中一个可选组件：

uv pip install -e "./tinker-atropos"

这些子模块都是完全可选的。如果跳过安装，相应功能会简单地不可用，不会影响核心功能的正常使用。

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

Node.js 依赖主要用于两项功能：基于 Browserbase 的浏览器自动化和 WhatsApp 桥接。如果不需要这些功能，可以跳过此步骤：

npm install

4.6 步骤六：创建配置目录结构

Hermes Agent 需要在用户主目录下创建配置文件夹和各类工作目录。执行以下命令完成目录创建和配置：

# 创建目录结构
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

各目录的用途说明如下：cron 用于存储定时任务配置；sessions 保存对话会话历史；logs 记录运行日志；memories 存储 AI 记忆数据；skills 存放自定义技能配置；pairing 用于配对设备；hooks 存放自定义钩子脚本；image_cache 和 audio_cache 分别缓存图像和音频文件；whatsapp/session 保存 WhatsApp 会话数据。

4.7 步骤七：配置 API 密钥

Hermes Agent 需要至少一个 LLM 提供商的 API 密钥才能正常工作。编辑 ~/.hermes/.env 文件，添加必要的密钥：

# 必需的密钥 - 至少需要一个 LLM 提供商
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# 可选密钥 - 启用额外工具
FIRECRAWL_API_KEY=fc-your-key          # 网络搜索和网页抓取
FAL_KEY=your-fal-key                   # 图像生成（FLUX 模型）

如果暂时没有这些密钥，也可以通过命令行方式逐步配置。使用 CLI 配置密钥的方式更加友好，会自动处理格式和加密：

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

4.8 步骤八：将 hermes 添加到 PATH

为了让 hermes 命令在系统任意位置可用，需要创建符号链接：

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 Shell 用户
fish_add_path $HOME/.local/bin

4.9 步骤九：配置 LLM 提供商

运行以下命令选择您偏好的 LLM 提供商和模型：

hermes model

该命令会启动交互式菜单，引导您选择提供商（如 OpenRouter、Anthropic、OpenAI 等）、输入 API 密钥、选择具体模型。这一步是可选的，您也可以直接编辑配置文件或在后续使用中随时调整。

4.10 步骤十：验证安装

完成安装后，使用以下命令验证一切正常：

hermes version    # 检查命令是否可用
hermes doctor     # 运行诊断程序检查环境
hermes status     # 查看当前配置状态
hermes chat -q "Hello! What tools do you have available?"

hermes doctor 命令尤其有用，它会详细检查各项依赖、环境变量、配置文件，并提供具体的修复建议。

五、安装后配置指南

安装完成后，根据您的使用场景，可能需要进行额外的配置。以下介绍常用的配置命令和功能说明。

5.1 基础配置命令

Hermes Agent 提供了丰富的配置命令，用于调整各项设置：

hermes model          # 选择 LLM 提供商和模型
hermes tools          # 配置启用的工具
hermes gateway setup  # 设置消息平台网关
hermes config set     # 设置单个配置项
hermes setup          # 运行完整的设置向导，一步配置所有选项

使用 hermes setup 命令是最全面的配置方式，它会依次引导您完成模型选择、工具配置、网关设置等所有步骤。

5.2 常用配置项说明

配置文件位于 ~/.hermes/config.yaml，支持多种配置方式。以下是一些常用配置项的示例：

# 模型配置
model:
  provider: openrouter
  model: anthropic/claude-3-5-sonnet

# 工具配置
tools:
  enabled:
    - web_search
    - file_search
    - image_generation
    - terminal

# 网关配置（可选）
gateway:
  telegram:
    enabled: true
    bot_token: "your-telegram-bot-token"

六、故障排除指南

在安装和使用过程中，可能会遇到一些常见问题。以下提供针对最常见问题的解决方案。

6.1 命令未找到问题

如果执行 hermes 命令时提示 command not found，请按以下步骤排查：首先确认符号链接是否正确创建，检查 ls -la ~/.local/bin/hermes 是否指向正确的位置；其次确认 PATH 配置是否生效，可以执行 echo $PATH | grep local/bin 查看；最后尝试重新加载 shell 配置，执行 source ~/.bashrc 或 source ~/.zshrc。

6.2 API 密钥未设置问题

如果启动时提示 API 密钥未设置，可以通过以下方式解决：运行 hermes model 命令重新配置提供商；或者使用 hermes config set OPENROUTER_API_KEY your_key 直接设置密钥；也可以手动编辑 ~/.hermes/.env 文件添加密钥。

6.3 更新后的配置迁移

当更新 Hermes Agent 后，如果出现配置相关问题，可以尝试以下命令：

hermes config check    # 检查配置完整性
hermes config migrate  # 迁移配置到新版本格式

对于其他问题，运行 hermes doctor 通常能提供最准确的诊断结果和修复建议。

七、快速参考命令汇总

为了方便经验丰富的用户快速部署，以下提供精简版的安装命令序列：

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

# 克隆仓库
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 创建虚拟环境
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=sk-or-v1-your-key' >> ~/.hermes/.env

# 创建全局命令
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

# 验证安装
hermes doctor
hermes

八、相关资源链接

完成安装后，建议进一步阅读以下资料以充分利用 Hermes Agent 的功能：

快速入门指南提供了从首次启动到完成第一个任务的全流程介绍；Android 与 Termux 指南专为移动设备用户编写，详细说明了在 Termux 环境中使用 Hermes Agent 的最佳实践；Nix 与 NixOS 设置指南为 Nix 系统用户提供了声明式配置方案；更新与卸载指南说明了如何保持 Hermes Agent 最新版本以及如何安全地移除安装。

您还可以加入 Discord 社区与其他用户交流使用经验，或访问 GitHub 仓库提交问题和建议。

---

通过本教程，您应该已经掌握了 Hermes Agent 的完整安装流程。无论选择快速安装还是手动安装方式，都能顺利启动并开始使用这个强大的 AI 代理工具。如有任何问题，欢迎查阅官方文档或参与社区讨论。

---

我来帮你获取并整理这份 Hermes Agent 的安装教程。
基于官方文档，我为你整理了一份完整的 Hermes Agent 安装教程。

---

Hermes Agent 完整安装指南

Hermes Agent 是由 NousResearch 开发的 AI 智能体框架，支持工具调用、浏览器自动化、消息平台集成等功能。本教程涵盖快速安装和手动安装两种方式。

一、系统要求

支持的平台

平台	支持状态	说明
Linux	✅ 完全支持	原生支持所有功能
macOS	✅ 完全支持	原生支持所有功能
WSL2 (Windows)	✅ 支持	Windows 用户需通过 WSL2 安装
Android (Termux)	✅ 支持	专用安装路径，部分功能受限
Windows (原生)	❌ 不支持	请使用 WSL2

唯一先决条件

只需要安装 Git，其他依赖（Python 3.11、Node.js、ffmpeg 等）都会自动安装：

git --version  # 验证 git 是否已安装

---

二、快速安装（推荐，2分钟内完成）

1. 执行一键安装脚本

Linux / macOS / WSL2：

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

Android / Termux：

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

Termux 版本会自动：

• 使用 pkg 安装系统依赖（git、python、nodejs、ripgrep、ffmpeg）
• 自动导出 ANDROID_API_LEVEL 环境变量
• 安装特调的 .[termux] 依赖包
• 跳过未测试的浏览器/WhatsApp 功能

2. 安装后操作

安装完成后，重新加载 shell 配置：

source ~/.bashrc   # 如果使用 bash
# 或
source ~/.zshrc    # 如果使用 zsh

3. 启动 Hermes

hermes  # 开始对话！

4. 后续配置

如需修改配置，使用以下命令：

hermes model          # 选择 LLM 提供商和模型
hermes tools          # 配置启用的工具
hermes gateway setup  # 设置消息平台（Telegram/Discord 等）
hermes config set     # 设置单个配置值
hermes setup          # 或运行完整设置向导

---

三、手动安装（完全控制）

如需完全控制安装过程，按以下步骤操作：

步骤 1：克隆仓库

必须包含子模块（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 已硬编码指向 venv 的 Python，创建符号链接后即可全局使用。

步骤 3：安装 Python 依赖

# 指定虚拟环境路径
export VIRTUAL_ENV="$(pwd)/venv"

# 安装完整版（包含所有功能）
uv pip install -e ".[all]"

可选依赖组件

功能	安装命令	说明
全部功能	uv pip install -e ".[all]"	安装所有组件
消息平台	uv pip install -e ".[messaging]"	Telegram、Discord、Slack
定时任务	uv pip install -e ".[cron]"	Cron 表达式解析
交互界面	uv pip install -e ".[cli]"	终端菜单界面
云执行	uv pip install -e ".[modal]"	Modal 云执行后端
高级语音	uv pip install -e ".[tts-premium]"	ElevenLabs 高级语音
语音输入	uv pip install -e ".[voice]"	麦克风输入 + 音频播放
终端支持	uv pip install -e ".[pty]"	PTY 终端支持
Android	uv pip install -e ".[termux]"	Termux 专用包
AI 记忆	uv pip install -e ".[honcho]"	Honcho 记忆集成
MCP 协议	uv pip install -e ".[mcp]"	Model Context Protocol
智能家居	uv pip install -e ".[homeassistant]"	Home Assistant 集成
开发测试	uv pip install -e ".[dev]"	pytest 和测试工具

组合安装示例：

uv pip install -e ".[messaging,cron]"

⚠️ Android 用户注意：.[all] 在 Android 上不可用（因为 voice 依赖 faster-whisper，而该包没有 Android 版本的 wheel）。请使用 .[termux]，然后根据需要单独添加其他组件。

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

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

如果跳过，相应的工具集将不可用。

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

仅在需要浏览器自动化和 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

# 创建环境变量文件（存储 API 密钥）
touch ~/.hermes/.env

步骤 7：配置 API 密钥

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

# 必需 - 至少一个 LLM 提供商：
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# 可选 - 启用额外工具：
FIRECRAWL_API_KEY=fc-your-key          # 网页搜索和抓取（或可自建）
FAL_KEY=your-fal-key                   # 图像生成（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  # 选择你的 LLM 提供商和模型

步骤 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

# 创建虚拟环境
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=sk-or-v1-your-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 配置提供商，或 hermes config set OPENROUTER_API_KEY your_key
更新后配置丢失	运行 hermes config check 然后 hermes config migrate
其他问题	运行 hermes doctor - 它会准确告诉你缺少什么以及如何修复

---

六、Nix 用户

如果你使用 Nix（NixOS、macOS 或 Linux），有专门的设置路径：

• Nix flake
• 声明式 NixOS 模块
• 可选容器模式

详情请参阅官方 Nix & NixOS 设置指南。

---

现在你可以开始使用 Hermes Agent 了！首次启动建议运行 hermes setup 完成完整的初始化向导。

---

Hermes Agent 完整安装与入门教程

Hermes Agent 是由 Nous Research 构建的自进化 AI 智能体。它内置学习循环——能从经验中创建技能、在使用中自我改进、自动持久化知识、搜索历史对话，并跨会话构建用户画像。支持在 $5 VPS、GPU 集群或 Serverless 基础设施上运行。

---

一、系统要求

项目	说明
操作系统	Linux、macOS、WSL2（Windows 通过 WSL2）、Android（通过 Termux）
唯一前置依赖	git（安装器会自动处理其余所有依赖）
最低上下文窗口	所选模型需至少 64K tokens 上下文
Windows	不支持原生 Windows，必须安装 WSL2

安装器会自动处理以下依赖，无需手动安装：

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

---

二、一键快速安装（推荐）

Linux / macOS / WSL2

打开终端，执行：

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

安装器会自动完成以下操作：

1. 检测操作系统类型
2. 安装缺失的系统依赖
3. 克隆仓库
4. 创建 Python 虚拟环境
5. 安装所有 Python 依赖
6. 配置全局 hermes 命令
7. 引导配置 LLM 提供商

Android / Termux

同样的命令也适用于 Termux，安装器会自动检测 Termux 环境并切换到 Android 流程：

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

Termux 下的特殊处理：

• 使用 pkg 安装系统依赖（git、python、nodejs、ripgrep、ffmpeg、构建工具）
• 使用 python -m venv 创建虚拟环境
• 自动导出 ANDROID_API_LEVEL 用于 Android wheel 构建
• 安装精选的 .[termux] 额外依赖（跳过 Android 不兼容的语音依赖）
• 默认跳过浏览器和 WhatsApp 引导

Windows 用户

1. 先安装 WSL2：

   wsl --install
   

2. 打开 WSL2 终端，执行上述安装命令。

安装完成后

source ~/.bashrc    # 重新加载 shell（如果是 zsh 则执行 source ~/.zshrc）
hermes              # 启动！

---

三、手动安装（完整控制）

如果你想完全掌控安装过程，可以按以下步骤操作。

第 1 步：克隆仓库

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 已硬编码指向 venv 中的 Python，建立全局符号链接后即可直接使用。

第 3 步：安装 Python 依赖

# 告诉 uv 使用哪个虚拟环境
export VIRTUAL_ENV="$(pwd)/venv"

# 安装全部额外依赖
uv pip install -e ".[all]"

如果只需要核心代理功能（不需要 Telegram/Discord/cron 支持）：

uv pip install -e "."

可选额外依赖一览：

额外标识	功能
.[voice]	语音模式（faster-whisper 本地语音转文字）
.[termux]	Android/Termux 精选依赖
.[acp]	ACP 编辑器集成（VS Code、Zed、JetBrains）
.[all]	全部功能

第 4 步：安装可选子模块

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

跳过此步不影响核心功能，对应的工具集将不可用。

第 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 密钥
touch ~/.hermes/.env

第 7 步：添加 API 密钥

编辑 ~/.hermes/.env，至少添加一个 LLM 提供商的密钥：

# 必需 — 至少配置一个 LLM 提供商：
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# 可选 — 启用额外工具：
FIRECRAWL_API_KEY=fc-your-key          # 网页搜索与抓取
FAL_KEY=your-fal-key                   # 图像生成（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 步：配置 LLM 提供商

hermes model       # 交互式选择 LLM 提供商和模型

第 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

# 创建虚拟环境
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=sk-or-v1-your-key' >> ~/.hermes/.env

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

# 验证
hermes doctor
hermes

---

五、LLM 提供商配置

Hermes 支持非常广泛的模型提供商，使用 hermes model 交互式配置：

提供商	说明	配置方式
Nous Portal	订阅制，零配置	通过 hermes model 进行 OAuth 登录
OpenRouter	路由 200+ 模型	输入 API Key
OpenAI	GPT 系列	输入 API Key
Anthropic	Claude 系列	API Key 或 Claude Code 认证
Hugging Face	20+ 开源模型	设置 HF_TOKEN
DeepSeek	DeepSeek API	设置 DEEPSEEK_API_KEY
Kimi / Moonshot	月之暗面模型	设置 KIMI_API_KEY
MiniMax	MiniMax 模型	设置 MINIMAX_API_KEY
阿里云	通义千问（DashScope）	设置 DASHSCOPE_API_KEY
GitHub Copilot	Copilot 订阅	OAuth 或 Token
自定义端点	vLLM、SGLang、Ollama 等	设置 Base URL + API Key

可以随时用 hermes model 切换提供商，无需修改代码。

---

六、启动与使用

启动 CLI 交互界面

hermes

你会看到欢迎界面，显示当前模型、可用工具和技能。输入消息后按 Enter 即可对话。

核心命令速查

命令	说明
hermes	启动交互式 CLI 聊天
hermes model	选择 LLM 提供商和模型
hermes tools	配置启用的工具
hermes config set	设置单个配置项
hermes gateway	启动消息网关（Telegram、Discord 等）
hermes setup	运行完整设置向导
hermes update	更新到最新版本
hermes doctor	诊断问题
hermes --continue / hermes -c	恢复最近的会话

CLI 内斜杠命令

在聊天界面中输入 / 查看自动补全菜单：

命令	功能
/help	显示所有可用命令
/tools	列出可用工具
/model	交互式切换模型
/new 或 /reset	开始新对话
/save	保存对话
/voice on	启用语音模式
/personality pirate	尝试趣味人格

实用技巧

• 多行输入：按 Alt+Enter 或 Ctrl+J 添加新行，适合粘贴代码或写详细提示
• 中断代理：代理执行任务时直接输入新消息并按 Enter 即可中断当前任务并切换指令；Ctrl+C 也可以

---

七、连接消息平台

Hermes 支持从 Telegram、Discord、Slack、WhatsApp、Signal、Email 等平台对话：

hermes gateway setup    # 交互式配置平台
hermes gateway start    # 启动网关

配置完成后，向对应平台的机器人发送消息即可开始对话。

---

八、进阶功能

沙箱终端

为安全起见，可在 Docker 容器或远程服务器中运行代理：

hermes config set terminal.backend docker    # Docker 隔离
hermes config set terminal.backend ssh       # 远程服务器

语音模式

pip install "hermes-agent[voice]"

启动后在 CLI 中启用：

/voice on

按 Ctrl+B 录音，或使用 /voice tts 让 Hermes 语音回复。

定时自动化任务

在对话中用自然语言描述：

每天早上 9 点，检查 Hacker News 的 AI 新闻，把摘要发到我的 Telegram。

代理会自动创建 cron 任务。

技能浏览与安装

hermes skills search kubernetes
hermes skills search react --source skills-sh
hermes skills install openai/skills/k8s
hermes skills install official/security/1password

ACP 编辑器集成

在 VS Code、Zed、JetBrains 等编辑器中使用 Hermes：

pip install -e '.[acp]'
hermes acp

MCP 服务器

在 ~/.hermes/config.yaml 中添加：

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

---

九、故障排除

问题	解决方案
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，它会精确告诉你缺什么以及如何修复

---

以上就是 Hermes Agent 从安装到入门的完整教程。如果你在某个步骤遇到问题，可以运行 hermes doctor 进行自动诊断，或者告诉我具体的报错信息，我来帮你排查。