Hermes Agent 完整安装部署指南#

Hermes Agent 是 Nous Research 推出的一款可成长的 AI Agent，主打自主学习、多层记忆架构和丰富的工具系统。这篇指南将带你从零开始完成安装部署。

项目简介#

项目	说明
开发团队	Nous Research
开源协议	MIT（完全免费）
核心卖点	闭环学习系统 + 四层记忆架构 + 40+ 内置工具
支持平台	Linux、macOS、WSL2、Android（Termux）
消息平台	Telegram、Discord、Slack、WhatsApp、飞书
支持模型	Claude、OpenRouter、DeepSeek、Qwen、Ollama 本地模型等

官方资源：

官网：https://hermes-agent.nousresearch.com
GitHub：https://github.com/NousResearch/hermes-agent

本文导航：

一、系统要求
二、环境准备
三、Windows WSL2 安装详解
四、快速安装（推荐）
五、手动安装（折腾版）
六、Docker 安装（零依赖）
七、配置 LLM 模型
八、常见问题排查（Windows WSL 专篇）
九、开始使用

一、系统要求 {#一系统要求}#

1.1 硬件配置#

配置项	最低要求	推荐配置
CPU	2 核	4 核以上
内存	4GB	8GB+
磁盘	2GB 可用	10GB+ 可用
网络	能访问 API	稳定宽带

1.2 操作系统支持#

✅ Linux（推荐 Ubuntu 22.04+）
✅ macOS（推荐 Sonoma 及以上）
✅ Windows（需通过 WSL2，详见第三章）
❌ 原生 Windows（不支持）

二、环境准备 {#二环境准备}#

2.1 安装 Git#

Git 是唯一需要手动安装的依赖，其他依赖都会由安装脚本自动处理。简单来说，Git 是一个版本控制工具，用来从 GitHub 下载和管理代码——你只需要装好它，后面的事情安装脚本会帮你搞定。

Linux（Ubuntu/Debian）：

1
sudo apt update
2
sudo apt install git -y

Linux（CentOS/RHEL）：

1
sudo yum install git -y

macOS： macOS 通常自带 Git，可通过以下命令验证：

1
git --version

如果没有安装，会提示安装 Xcode Command Line Tools，按提示操作即可。

Windows（WSL2）： 先安装 WSL2，然后在 WSL2 中安装 Git：

1
sudo apt update
2
sudo apt install git -y

2.2 中国大陆网络加速（可选）#

如果你在中国大陆，建议提前配置镜像源以加速安装：

Git 镜像：

1
git config --global url."https://mirror.ghproxy.com/https://github.com".insteadOf "https://github.com"

pip 镜像：

1
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
2
pip config set install.trusted-host mirrors.aliyun.com

npm 镜像：

1
npm config set registry https://mirrors.cloud.tencent.com/npm/ --global

三、Windows WSL2 安装详解 {#三windows-wsl2-安装详解}#

Windows 用户需要通过 WSL2（Windows Subsystem for Linux）来运行 Hermes Agent。这是目前 Windows 上最稳定的运行方式。

3.1 安装 WSL2#

方法一：自动安装（推荐）

以管理员身份打开 PowerShell，运行：

1
wsl --install

这会安装 WSL2 和默认的 Ubuntu 发行版。安装完成后重启电脑，然后设置 Ubuntu 用户名和密码。

方法二：手动安装

如果自动安装失败，可以手动安装：

1
# 启用 WSL
2
wsl --install --no-distribution
3

4
# 查看可用的 Linux 发行版
5
wsl --list --online
6

7
# 安装 Ubuntu 22.04
8
wsl --install -d Ubuntu-22.04

验证 WSL 安装：

1
wsl --version
2
wsl --list --verbose

3.2 配置 WSL2（性能优化）#

WSL2 默认配置可能占用较多内存，建议创建 .wslconfig 文件进行优化。

在用户目录（C:\Users\你的用户名）创建 .wslconfig 文件：

1
[wsl2]
2
# 限制 WSL2 最大内存使用
3
memory=4GB
4

5
# 限制 WSL2 处理器使用
6
processors=2
7

8
# 设置 WSL2 交换文件大小
9
swap=2GB
10

11
# 开启 localhost 转发
12
localhostForwarding=true
13

14
# 设置 WSL2 为默认版本
15
defaultVersion=2

配置完成后，在 PowerShell 中重启 WSL：

1
wsl --shutdown
2
wsl

3.3 WSL2 基础配置#

进入 WSL2 后，先更新系统：

1
sudo apt update && sudo apt upgrade -y

设置时区（重要）：

1
# 查看当前时区
2
date
3

4
# 设置为中国时区
5
sudo timedatectl set-timezone Asia/Shanghai
6

7
# 验证
8
date

配置中文显示（可选）：

1
# 安装中文语言包
2
sudo apt install language-pack-zh-hans -y
3

4
# 设置 locale
5
sudo locale-gen zh_CN.UTF-8
6
sudo update-locale LANG=zh_CN.UTF-8

3.4 WSL2 文件互访#

在 Windows 中访问 WSL 文件：

在文件资源管理器地址栏输入：

1
\\wsl$\Ubuntu\home\你的用户名

在 WSL 中访问 Windows 文件：

1
# Windows C盘
2
cd /mnt/c
3

4
# Windows D盘
5
cd /mnt/d
6

7
# 用户目录
8
cd /mnt/c/Users/你的用户名

⚠️ 重要提示：

在 WSL 中处理文件比在 Windows 中访问 WSL 文件性能更好
建议将项目文件放在 WSL 的 home 目录下（/home/用户名）
Hermes Agent 的配置和数据最好都保存在 WSL 内部

3.5 安装 Windows Terminal（推荐）#

Windows Terminal 提供了更好的终端体验，支持多标签页、自定义主题等。

安装方法：

打开 Microsoft Store
搜索 “Windows Terminal”
点击安装

配置默认启动 WSL：

打开 Windows Terminal 设置（Ctrl + ,），将默认配置文件设置为 Ubuntu。

四、快速安装（推荐） {#四快速安装推荐}#

这是最简单的安装方式，一键脚本自动处理所有依赖。

4.1 Linux / macOS / WSL2#

打开终端，执行以下命令：

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

或者使用 wget：

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

中国大陆用户推荐使用中文社区镜像：

1
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

脚本会自动完成以下操作：

检测系统架构（x86_64 / arm64）
安装 uv、Python 3.11、Node.js v22
克隆 Hermes Agent 仓库
创建 Python 虚拟环境并安装依赖
注册 hermes 全局命令

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

这是因为安装脚本修改了 shell 配置文件（~/.bashrc），需要让终端重新读取才能识别 hermes 命令。你也可以直接关闭终端再重新打开，效果一样。

1
# bash 用户
2
source ~/.bashrc
3

4
# zsh 用户（macOS 默认）
5
source ~/.zshrc

验证安装：

1
hermes --version

如果输出了版本号，说明安装成功！

4.2 Windows 原生 PowerShell#

如果你不想安装 WSL2，可以直接使用 PowerShell 版本：

1
irm https://res1.hermesagent.org.cn/install.ps1 | iex

安装完成后，关闭并重新打开 PowerShell，然后输入：

1
hermes

五、手动安装（折腾版） {#五手动安装折腾版}#

如果你想完全掌控安装过程，可以选择手动安装。

5.1 克隆仓库#

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

如果克隆时忘了 --recurse-submodules，补一下：

1
git submodule update --init --recursive

5.2 安装 uv 和虚拟环境#

uv 是一个用 Rust 写的超快速 Python 包管理器，比传统的 pip 快 10-100 倍。虚拟环境则是一个独立的 Python 运行空间，避免 Hermes 的依赖和你系统上其他 Python 项目的依赖互相干扰。

1
curl -LsSf https://astral.sh/uv/install.sh | sh
2
uv venv venv --python 3.11

5.3 安装依赖#

1
export VIRTUAL_ENV="$(pwd)/venv"
2
uv pip install -e ".[all]"

各模块说明：

模块	功能	安装命令
核心	基础功能	`uv pip install -e "."`
messaging	Telegram/Discord 网关	`uv pip install -e ".[messaging]"`
cron	定时任务	`uv pip install -e ".[cron]"`
voice	麦克风+音频播放	`uv pip install -e ".[voice]"`
mcp	MCP 支持	`uv pip install -e ".[mcp]"`
slack	Slack 消息	`uv pip install -e ".[slack]"`
honcho	AI 原生记忆	`uv pip install -e ".[honcho]"`

5.4 创建配置目录和文件#

1
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
2
cp cli-config.yaml.example ~/.hermes/config.yaml
3
touch ~/.hermes/.env

5.5 添加 API Key#

编辑 ~/.hermes/.env 文件，添加你的 API Key：

1
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key-here' >> ~/.hermes/.env

5.6 添加到 PATH#

PATH 是系统用来查找可执行程序的目录列表。这一步把 hermes 命令所在的目录加到 PATH 中，这样你在任何位置输入 hermes 都能运行，而不需要每次切换到安装目录。

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

4
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
5
source ~/.bashrc

5.7 验证安装#

1
hermes version   # 检查命令是否可用
2
hermes doctor    # 运行诊断
3
hermes chat -q "Hello! What tools do you available?"  # 测试对话

六、Docker 安装（零依赖） {#六docker-安装零依赖}#

如果你不想安装 Python 环境，可以使用 Docker。前提是你已经安装了 Docker Desktop 或 Docker Engine——如果还没装，先去 docker.com 下载安装。

6.1 拉取镜像#

1
docker pull nousresearch/hermes-agent:latest

6.2 交互式运行#

1
docker run -it --rm \
2
  -v ~/.hermes:/home/hermes/.hermes \
3
  -v ~/.ssh:/home/hermes/.ssh:ro \
4
  -e OPENROUTER_API_KEY=sk-or-xxx \
5
  nousresearch/hermes-agent:latest

6.3 使用 Docker Compose#

创建 docker-compose.yml：

1
version: '3'
2
services:
3
  hermes:
4
    image: nousresearch/hermes-agent:latest
5
    volumes:
6
      - ~/.hermes:/home/hermes/.hermes
7
      - ~/.ssh:/home/hermes/.ssh:ro
8
    environment:
9
      - OPENROUTER_API_KEY=sk-or-xxx
10
    stdin_open: true
11
    tty: true

然后运行：

1
docker compose up -d
2
docker compose exec hermes hermes

七、配置 LLM 模型 {#七配置-llm-模型}#

安装好之后，需要配置 LLM 提供商。

7.1 使用交互式向导#

1
hermes setup

这会启动一个交互式向导，引导你完成：

选择模型提供商
输入 API Key
基本偏好设置

7.2 常用模型提供商#

新手推荐： 国内用户首选 DeepSeek（注册简单、性价比高），海外用户可选 OpenRouter（注册即送额度，支持模型多）。如果你注重隐私或想完全免费，可以选 Ollama 本地部署。

提供商	配置方式	说明
Nous Portal	OAuth 登录，零配置	官方订阅服务，最简单
Anthropic Claude	API Key 或 Claude Code 授权	注意：目前尚未被封禁
OpenRouter	API Key	支持 200+ 模型，灵活度高
DeepSeek	API Key	国内用户友好，性价比高
阿里云 DashScope	API Key	支持 Qwen 系列
Ollama	本地运行	完全离线，隐私优先
自定义端点	OpenAI 兼容 API	vLLM、SGLang 等

7.3 配置示例#

使用 DeepSeek：

1
hermes config set model deepseek/deepseek-chat
2
hermes config set DEEPSEEK_API_KEY sk-your-key-here

使用 Ollama 本地模型：

1
# 先启动 Ollama
2
ollama serve
3

4
# 配置 Hermes 使用本地模型
5
hermes config set model ollama/llama3

八、常见问题排查（Windows WSL 专篇） {#八常见问题排查windows-wsl-专篇}#

8.1 WSL2 安装问题#

问题 1：WSL 安装失败，提示 “无法解析服务器名称或地址”

原因： 网络问题或 DNS 解析失败。

解决：

1
# 以管理员身份运行 PowerShell
2
# 重置 Winsock
3
netsh winsock reset
4

5
# 重置网络适配器
6
netsh int ip reset
7

8
# 刷新 DNS
9
ipconfig /flushdns
10

11
# 重启电脑

问题 2：WSL2 启动失败，提示 “参考的对象类型不支持尝试的操作”

原因： 其他虚拟化软件（如 VMware、VirtualBox）冲突。

解决：

1
# 以管理员身份运行 PowerShell
2
# 禁用 Hyper-V 独占模式
3
bcdedit /set hypervisorlaunchtype auto
4

5
# 重启电脑

问题 3：WSL 提示 “Error: 0x80040306”

原因： WSL 内核版本过旧。

解决：

1
# 更新 WSL
2
wsl --update
3

4
# 如果更新失败，手动下载安装
5
# 访问 https://aka.ms/wsl2kernel 下载并安装

8.2 WSL2 性能问题#

问题：WSL2 占用内存过大，导致 Windows 卡顿

解决： 配置 .wslconfig 限制资源使用：

1
[wsl2]
2
memory=4GB
3
processors=2
4
swap=2GB
5
localhostForwarding=true

然后执行：

1
wsl --shutdown

问题：文件访问速度很慢

原因： 跨系统（Windows ↔ WSL）文件访问性能较差。

解决：

将项目文件放在 WSL 内部（/home/用户名）
避免在 Windows 文件系统中运行 WSL 程序
使用 wsl --mount 挂载磁盘（如果需要访问 Windows 磁盘）

8.3 网络连接问题#

问题 1：WSL2 无法访问网络

解决：

1
# 在 WSL 中执行
2
sudo rm /etc/resolv.conf
3
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
4
sudo bash -c 'echo "nameserver 114.114.114.114" >> /etc/resolv.conf'
5
sudo chattr +i /etc/resolv.conf

问题 2：Hermes 无法连接到 API

原因： 防火墙或代理问题。

解决：

1
# 测试 API 连接
2
curl -v https://api.openai.com/v1/models
3

4
# 如果需要代理
5
export https_proxy=http://your-proxy:port
6
export http_proxy=http://your-proxy:port
7

8
# 添加到 ~/.bashrc 使其永久生效
9
echo 'export https_proxy=http://your-proxy:port' >> ~/.bashrc
10
source ~/.bashrc

8.4 Hermes 安装问题#

问题 1：hermes: command not found

原因： 没有重新加载 shell 配置，或 PATH 配置有误。

解决：

1
# 重新加载 shell
2
source ~/.bashrc  # 或 source ~/.zshrc
3

4
# 检查 PATH
5
echo $PATH
6

7
# 手动添加 PATH
8
export PATH="$HOME/.local/bin:$PATH"
9

10
# 永久添加到 PATH
11
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
12
source ~/.bashrc

问题 2：安装脚本执行失败

原因： 权限问题或网络问题。

解决：

1
# 手动下载脚本
2
curl -fsSL https://res1.hermesagent.org.cn/install.sh -o install.sh
3

4
# 查看脚本内容（可选）
5
cat install.sh
6

7
# 执行脚本
8
chmod +x install.sh
9
bash install.sh

问题 3：Python 版本不兼容

解决：

1
# 检查 Python 版本
2
python3 --version
3

4
# 如果版本低于 3.11，需要升级
5
# 安装 pyenv 管理 Python 版本
6
curl https://pyenv.run | bash
7

8
# 添加到 shell 配置
9
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
10
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
11
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
12
source ~/.bashrc
13

14
# 安装 Python 3.11
15
pyenv install 3.11.9
16
pyenv global 3.11.9

问题 4：API key not set

原因： 没有配置模型提供商。

解决：

1
# 运行模型配置向导
2
hermes model
3

4
# 或直接设置
5
hermes config set OPENROUTER_API_KEY your_key
6

7
# 验证配置
8
hermes config get OPENROUTER_API_KEY

8.5 运行时报错#

问题 1：“ModuleNotFoundError” 或 “ImportError”

原因： 依赖包安装不完整。

解决：

1
# 进入 Hermes 安装目录
2
cd ~/hermes-agent
3

4
# 激活虚拟环境
5
source venv/bin/activate
6

7
# 重新安装依赖
8
uv pip install -e ".[all]"
9

10
# 验证安装
11
hermes doctor

问题 2：“Permission denied” 错误

解决：

1
# 修复权限
2
sudo chown -R $USER:$USER ~/.hermes
3
sudo chmod -R 755 ~/.hermes
4

5
# 如果问题持续，检查 SELinux/AppArmor
6
sudo apt install apparmor-utils
7
sudo aa-disable /etc/apparmor.d/hermes

问题 3：内存不足导致程序崩溃

解决：

1
# 检查内存使用
2
free -h
3

4
# 清理缓存
5
sudo sync && sudo sysctl -w vm.drop_caches=3
6

7
# 增加 WSL2 内存限制（在 .wslconfig 中）
8
# memory=8GB
9

10
# 重启 WSL
11
wsl --shutdown

8.6 配置问题#

问题：Hermes 无法保存配置

原因： 配置目录权限问题。

解决：

1
# 创建配置目录
2
mkdir -p ~/.hermes
3

4
# 设置权限
5
chmod 755 ~/.hermes
6

7
# 验证配置目录
8
ls -la ~/.hermes
9

10
# 手动创建配置文件
11
touch ~/.hermes/config.yaml
12
touch ~/.hermes/.env

问题：时区不正确导致日志时间错误

解决：

1
# 设置时区
2
sudo timedatectl set-timezone Asia/Shanghai
3

4
# 验证
5
date
6

7
# 同步时间
8
sudo apt install ntpdate
9
sudo ntpdate time.windows.com

九、开始使用 {#九开始使用}#

配置好后，直接输入：

1
hermes

即可进入全交互式终端界面，开始和 Agent 对话。

常用命令：

命令	说明
`hermes`	启动交互式 CLI 聊天
`hermes setup`	运行完整设置向导
`hermes model`	切换模型提供商和模型
`hermes tools`	配置启用的工具
`hermes gateway`	启动消息网关（Telegram 等）
`hermes update`	更新到最新版本
`hermes doctor`	诊断问题

8.7 实用技巧与命令#

WSL2 常用命令速查：

1
# PowerShell 中执行
2

3
# 查看 WSL 状态
4
wsl --status
5

6
# 列出所有发行版
7
wsl --list --verbose
8

9
# 关闭所有 WSL 发行版
10
wsl --shutdown
11

12
# 终止特定发行版
13
wsl -t Ubuntu
14

15
# 导出 WSL 备份
16
wsl --export Ubuntu D:\backup\ubuntu.tar
17

18
# 导入 WSL 备份
19
wsl --import UbuntuNew D:\WSL\UbuntuNew D:\backup\ubuntu.tar
20

21
# 设置默认发行版
22
wsl --set-default Ubuntu
23

24
# 设置 WSL 版本
25
wsl --set-version Ubuntu 2

Hermes 常用诊断命令：

1
# 检查 Hermes 状态
2
hermes doctor
3

4
# 查看配置
5
hermes config list
6

7
# 测试模型连接
8
hermes chat -q "Hello"
9

10
# 查看日志
11
tail -f ~/.hermes/logs/hermes.log
12

13
# 更新 Hermes
14
cd ~/hermes-agent
15
git pull
16
source venv/bin/activate
17
uv pip install -e ".[all]"

Windows 与 WSL 协同技巧：

在 Windows 中打开 WSL 目录：
Terminal window
```
1
explorer.exe \\wsl$\Ubuntu\home\用户名
```

在 WSL 中打开 Windows 程序：

1
notepad.exe filename.txt
2
code .  # VS Code
3
explorer.exe .  # 文件资源管理器

使用 VS Code 远程开发（推荐）：
- 在 Windows 安装 VS Code
- 安装 “WSL” 扩展
- 在 WSL 中运行 code . 即可在 Windows 上编辑 WSL 文件

写在最后#

Hermes Agent 在 WSL2 上运行非常稳定，配合 Windows Terminal 和 VS Code 可以获得很好的开发体验。如果在安装过程中遇到问题，建议：

先确保 WSL2 本身能正常运行
网络连接畅通（可以访问 GitHub 和 API）
按照本文的常见问题排查步骤逐一检查
必要时查看官方文档或 GitHub Issues

记忆系统和技能系统是这个 Agent 的亮点——不是简单的对话历史，而是会主动整理和沉淀知识。技能系统也挺好用，学到的东西可以跨会话复用。

当然，作为开源项目，它还在快速迭代中，有些功能还在完善。感兴趣的可以试试，有问题可以去 GitHub 提 Issue。

祝你使用愉快！

音乐

音乐

28.Hermes Agent 完整安装部署指南

Hermes Agent 完整安装部署指南#

项目简介#

一、系统要求 {#一系统要求}#

1.1 硬件配置#

1.2 操作系统支持#

二、环境准备 {#二环境准备}#

2.1 安装 Git#

2.2 中国大陆网络加速（可选）#

三、Windows WSL2 安装详解 {#三windows-wsl2-安装详解}#

3.1 安装 WSL2#

3.2 配置 WSL2（性能优化）#

3.3 WSL2 基础配置#

3.4 WSL2 文件互访#

3.5 安装 Windows Terminal（推荐）#

四、快速安装（推荐） {#四快速安装推荐}#

4.1 Linux / macOS / WSL2#

4.2 Windows 原生 PowerShell#

五、手动安装（折腾版） {#五手动安装折腾版}#

5.1 克隆仓库#

5.2 安装 uv 和虚拟环境#

5.3 安装依赖#

5.4 创建配置目录和文件#

5.5 添加 API Key#

5.6 添加到 PATH#

5.7 验证安装#

六、Docker 安装（零依赖） {#六docker-安装零依赖}#

6.1 拉取镜像#

6.2 交互式运行#

6.3 使用 Docker Compose#

七、配置 LLM 模型 {#七配置-llm-模型}#

7.1 使用交互式向导#

7.2 常用模型提供商#

7.3 配置示例#

八、常见问题排查（Windows WSL 专篇） {#八常见问题排查windows-wsl-专篇}#

8.1 WSL2 安装问题#

8.2 WSL2 性能问题#

8.3 网络连接问题#

8.4 Hermes 安装问题#

8.5 运行时报错#

8.6 配置问题#

九、开始使用 {#九开始使用}#

8.7 实用技巧与命令#

写在最后#

支持与分享

评论区

音乐

目录