安装

本文介绍如何在你的机器上安装 Hermes Agent。

系统要求

操作系统

系统	支持状态
Linux	完整支持
macOS	完整支持
WSL2（Windows 子系统）	完整支持
Windows 原生	不支持

注意：Hermes Agent 不支持 Windows 原生环境。Windows 用户请使用 WSL2（推荐 Ubuntu 22.04）。

前置依赖

安装前唯一需要手动准备的工具是 Git：

bash

# Ubuntu/Debian
sudo apt install git

# macOS（通过 Homebrew）
brew install git

# 验证
git --version

其余所有依赖（uv、Python 3.11、Node.js v22、ripgrep、ffmpeg 等）均由安装脚本自动处理。

方式一：一键安装（推荐）

这是最简单的安装方式，适合大多数用户：

bash

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

安装完成后，使环境变量生效：

bash

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

自动安装的依赖

一键安装脚本会自动检测并安装以下所有依赖：

依赖	版本	用途
uv	最新版	Python 包管理器
Python	3.11	运行时环境
Node.js	v22	前端工具链
ripgrep	最新版	高速文件内容搜索
ffmpeg	最新版	音视频处理（语音功能）

验证安装

bash

hermes doctor

hermes doctor 会检查所有依赖和配置项，输出类似：

✓ Python 3.11.9
✓ Node.js v22.4.0
✓ uv 0.4.1
✓ ripgrep 14.1.0
✓ ffmpeg 6.1.1
✓ ~/.hermes 目录结构
✓ ~/.hermes/.env 配置文件
⚠ 未检测到 API Key，请运行 hermes setup

方式二：手动安装

如果你需要更精细的控制，可以按以下步骤手动安装：

第 1 步：克隆仓库

bash

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

--recurse-submodules 参数会同时克隆所有子模块，不可省略。

第 2 步：创建虚拟环境

bash

uv venv .venv --python 3.11
source .venv/bin/activate

第 3 步：安装 Python 依赖

bash

pip install -e .

第 4 步：创建配置目录结构

bash

mkdir -p ~/.hermes/{skills,memory,personas,logs}

目录说明：

目录	用途
`~/.hermes/skills/`	存放自动生成和手动创建的技能文件
`~/.hermes/memory/`	持久记忆数据库
`~/.hermes/personas/`	人格/角色配置文件
`~/.hermes/logs/`	运行日志

第 5 步：创建环境变量文件

bash

touch ~/.hermes/.env

编辑 ~/.hermes/.env，填入你的 API Key（至少填一个）：

bash

# Nous Portal（推荐）
NOUS_API_KEY=your_key_here

# OpenRouter（可访问 200+ 模型）
OPENROUTER_API_KEY=your_key_here

# OpenAI
OPENAI_API_KEY=your_key_here

# Anthropic
ANTHROPIC_API_KEY=your_key_here

# Google Gemini
GOOGLE_API_KEY=your_key_here

第 6 步：创建配置文件

bash

cp config.example.yaml ~/.hermes/config.yaml

第 7 步：创建命令软链接

bash

sudo ln -sf "$(pwd)/.venv/bin/hermes" /usr/local/bin/hermes

第 8 步：验证安装

bash

hermes doctor

第 9 步：运行初始化向导

bash

hermes setup

第 10 步：开始使用

bash

hermes

可选功能包

Hermes Agent 的部分功能需要额外安装依赖包。通过 pip 的 extras 语法按需安装：

单独安装

bash

# 语音输入/输出支持
pip install "hermes-agent[voice]"

# 消息平台集成
pip install "hermes-agent[messaging]"

# 高质量 TTS（文字转语音）
pip install "hermes-agent[tts-premium]"

# 浏览器自动化
pip install "hermes-agent[browser]"

# 图片生成
pip install "hermes-agent[image]"

# 向量数据库（增强记忆检索）
pip install "hermes-agent[vector]"

# OpenTelemetry 可观测性
pip install "hermes-agent[observability]"

完整安装（所有功能）

bash

pip install "hermes-agent[all]"

可用 extras 列表

Extra 名称	包含功能
`voice`	语音识别（Whisper）、语音活动检测
`messaging`	Telegram、Discord、Slack、WhatsApp 等平台 SDK
`tts-premium`	ElevenLabs、Azure TTS 等高质量语音合成
`browser`	Playwright 浏览器自动化
`image`	Stable Diffusion、DALL-E 图片生成接口
`vector`	ChromaDB、Qdrant 向量存储
`observability`	OpenTelemetry 链路追踪
`dev`	开发工具（pytest、ruff、mypy 等）
`docs`	文档构建工具（MkDocs）
`hpc`	HPC/Singularity 集群支持
`modal`	Modal 无服务器执行后端
`daytona`	Daytona 云开发环境后端
`ssh`	增强 SSH 远程执行支持
`docker`	Docker 容器执行后端
`security`	Tirith 安全扫描集成
`all`	以上所有功能

Docker 部署

如果你希望将 Hermes Agent 完全容器化运行：

拉取镜像

bash

docker pull nousresearch/hermes-agent:latest

运行容器

bash

docker run -it \
  -v ~/.hermes:/root/.hermes \
  -e OPENAI_API_KEY=your_key_here \
  nousresearch/hermes-agent:latest

使用 Docker Compose

创建 docker-compose.yml：

yaml

version: "3.9"
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    volumes:
      - ~/.hermes:/root/.hermes
    environment:
      - NOUS_API_KEY=${NOUS_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    stdin_open: true
    tty: true
    restart: unless-stopped

启动：

bash

docker compose up -d
docker compose exec hermes hermes

Nix / NixOS 支持

Hermes Agent 提供 Nix Flake 支持，适合 NixOS 用户或使用 Nix 包管理器的开发者：

临时运行（无需安装）

bash

nix run github:NousResearch/hermes-agent

加入 NixOS 配置

在你的 flake.nix 中添加：

nix

{
  inputs.hermes-agent.url = "github:NousResearch/hermes-agent";

  outputs = { self, nixpkgs, hermes-agent, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [
        hermes-agent.nixosModules.default
        {
          services.hermes-agent = {
            enable = true;
            configFile = "/etc/hermes/config.yaml";
          };
        }
      ];
    };
  };
}

开发 Shell

bash

nix develop github:NousResearch/hermes-agent

升级

一键安装方式升级

bash

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

重新运行安装脚本会自动升级到最新版本。

手动安装方式升级

bash

cd hermes-agent
git pull --recurse-submodules
pip install -e .
hermes config migrate  # 如有配置格式变更，自动迁移

检查当前版本

bash

hermes --version

常见安装问题

`hermes: command not found`

软链接未生效，请运行：

bash

source ~/.bashrc  # 或 source ~/.zshrc

如果仍然不行，检查 /usr/local/bin 是否在 PATH 中：

bash

echo $PATH | grep -o '/usr/local/bin'

Python 版本冲突

Hermes Agent 需要 Python 3.11。使用 uv 可以自动管理版本：

bash

uv python install 3.11
uv venv .venv --python 3.11

子模块缺失

如果克隆时忘记了 --recurse-submodules：

bash

git submodule update --init --recursive

`hermes doctor` 报告缺失依赖

根据 hermes doctor 的输出，单独安装缺失的工具：

bash

# 缺少 ripgrep
sudo apt install ripgrep  # Ubuntu
brew install ripgrep      # macOS

# 缺少 ffmpeg
sudo apt install ffmpeg   # Ubuntu
brew install ffmpeg       # macOS

安装 ​

系统要求 ​

操作系统 ​

前置依赖 ​

方式一：一键安装（推荐） ​

自动安装的依赖 ​

验证安装 ​

方式二：手动安装 ​

第 1 步：克隆仓库 ​

第 2 步：创建虚拟环境 ​

第 3 步：安装 Python 依赖 ​

第 4 步：创建配置目录结构 ​

第 5 步：创建环境变量文件 ​

第 6 步：创建配置文件 ​

第 7 步：创建命令软链接 ​

第 8 步：验证安装 ​

第 9 步：运行初始化向导 ​

第 10 步：开始使用 ​

可选功能包 ​

单独安装 ​

完整安装（所有功能） ​

可用 extras 列表 ​

Docker 部署 ​

拉取镜像 ​

运行容器 ​

使用 Docker Compose ​

Nix / NixOS 支持 ​

临时运行（无需安装） ​

加入 NixOS 配置 ​

开发 Shell ​

升级 ​

一键安装方式升级 ​

手动安装方式升级 ​

检查当前版本 ​

常见安装问题 ​

hermes: command not found ​

Python 版本冲突 ​

子模块缺失 ​

hermes doctor 报告缺失依赖 ​

安装

系统要求

操作系统

前置依赖

方式一：一键安装（推荐）

自动安装的依赖

验证安装

方式二：手动安装

第 1 步：克隆仓库

第 2 步：创建虚拟环境

第 3 步：安装 Python 依赖

第 4 步：创建配置目录结构

第 5 步：创建环境变量文件

第 6 步：创建配置文件

第 7 步：创建命令软链接

第 8 步：验证安装

第 9 步：运行初始化向导

第 10 步：开始使用

可选功能包

单独安装

完整安装（所有功能）

可用 extras 列表

Docker 部署

拉取镜像

运行容器

使用 Docker Compose

Nix / NixOS 支持

临时运行（无需安装）

加入 NixOS 配置

开发 Shell

升级

一键安装方式升级

手动安装方式升级

检查当前版本

常见安装问题

`hermes: command not found`

Python 版本冲突

子模块缺失

`hermes doctor` 报告缺失依赖