Hermes 完整安装指南

2026年，AI Agent赛道持续火热。如果你关注开源Agent社区，一定听说过 Hermes 。它由 Nous Research 开发，开源仅半年便在 GitHub 斩获 5.3 万颗星，成为史上增长最快的 AI Agent 项目之一。

但真正让 Hermes Agent 出圈的，不是它惊人的星标数字，而是它的核心理念："一个与你共同成长的 Agent"。它不像传统聊天AI那样"用完即忘"，而是可以从你的使用中学习、创建技能、持久化知识，真正成为你的数字分身。

这篇文章将帮你从零开始，在 Mac、Windows、Linux 三大平台完成 Hermes Agent 的完整安装与配置。无论你是技术小白还是资深开发者，都能找到适合自己的安装方案。

一、Hermes Agent 到底是什么？

在正式安装之前，我们先来了解一下 Hermes Agent 到底是什么，它和其他 AI 工具有什么不同。

1.1 什么是 Hermes Agent？

Hermes Agent 是由 AI 研究组织 Nous Research 开发的开源自主 AI 代理（MIT 许可证）。它的定位不是一个简单的聊天工具，而是一个"能与你共同成长的 AI Agent"。

你可以这样理解：传统的 ChatGPT 就像一个每次都要重新认识的陌生人，你关闭对话窗口，它就忘记了你们之前聊过什么。但 Hermes Agent 不一样，它可以记住你的偏好、学习你的工作方式，甚至在你关闭会话后依然保留上下文。

1.2 Hermes Agent 的核心特性

Hermes Agent 之所以能快速出圈，主要因为它踩中了 AI Agent 赛道的几个关键词：

第一个特性是自我学习循环。Hermes Agent 能够从经验中创建技能、在使用中改进技能、主动持久化知识。这意味着它会越用越懂你，越用越高效。

第二个特性是多模型支持。Hermes Agent 不绑定任何特定模型，你可以通过配置自由切换 GPT-4、Claude、Ollama 本地模型等。这种灵活性在同类工具中非常罕见。

第三个特性是丰富的工具生态。Hermes Agent 内置了 17 个常用工具集，包括 web（网页搜索）、terminal（终端）、file（文件操作）、browser（浏览器）、vision（图像识别）、image_gen（图片生成）、skills（技能创建）、tts（语音合成）等。

第四个特性是持久化记忆。通过 SOUL.md 文件，Hermes Agent 可以在跨会话中构建对用户的深度理解。你可以让它记住你的工作习惯、偏好设置，甚至个人特征。

1.3 谁适合使用 Hermes Agent？

根据社区反馈，以下三类人最适合使用 Hermes Agent：

第一类是研究 AI Agent 工作流的开发者。Hermes Agent 的代码完全开源，架构清晰，非常适合用来研究 Agent 的工作原理。

第二类是想做 AI 产品原型的人。如果你 是产品经理或创业者，Hermes Agent 可以帮助你理解"一个有长期价值的 Agent 产品应该长什么样"。

第三类是想搭建个人 AI 工作台的人。从 Web Workspace、Desktop Companion 这些方向看，Hermes Agent 已经不只是 CLI 工具，而是在往"AI 工作台"演进。

二、安装前准备：环境检查与依赖

在开始安装之前，我们需要确认你的系统环境是否满足要求。这一步很重要，很多安装失败都是因为环境问题。

2.1 系统要求

Hermes Agent 支持以下操作系统：

macOS：版本 12.0 及以上（M1/M2/M3 芯片的 Mac 推荐使用）

Linux：Ubuntu 20.04+、Debian 11+、Fedora 38+

Windows：需要通过 WSL2（Windows Subsystem for Linux 2）安装

硬件要求方面，建议内存至少 16GB，硬盘可用空间至少 20GB。如果你想运行本地大模型，显卡显存建议 8GB 以上。

2.2 必要软件检查

Hermes Agent 的运行依赖以下软件：

第一个是 Python 3.10+。你可以打开终端，输入 python3 --version 来检查。如果显示版本号低于 3.10，需要升级 Python。

第二个是 Git。输入 git --version 检查。如果没有，安装命令如下：

macOS：brew install git

Ubuntu/Debian：sudo apt install -y git

第三个是 curl。输入 curl --version 检查。macOS 和大多数 Linux 发行版默认已安装。

第四个是 uv。这是 Astral 开发的超快 Python 包管理器，Hermes Agent 推荐使用 uv 进行安装。安装命令：

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

Windows（PowerShell）：irm https://astral.sh/uv/install.ps1 | iex

安装完成后，运行 uv --version 确认安装成功。

2.3 可选软件

除了必要软件，以下软件可以让 Hermes Agent 的体验更完整：

pnpm：很多 JavaScript/TypeScript 项目推荐使用 pnpm。安装命令：

macOS：brew install pnpm

Ubuntu/Debian：sudo apt install -y pnpm

Ollama：如果你想运行本地大模型，需要安装 Ollama。安装命令：

macOS/Linux：curl -fsSL https://ollama.com/install.sh | sh

Docker：如果你想用 Docker 方式运行 Hermes Agent，需要安装 Docker Desktop。下载地址：https://www.docker.com/products/docker-desktop/

2.4 API Key 准备

Hermes Agent 需要连接大语言模型来提供 AI 能力。在安装之前，你需要准备至少一个 API Key：

如果你使用 OpenAI：需要获取 OpenAI API Key。访问 https://platform.openai.com/api-keys 创建。注意：GPT-4o 的价格较高，新用户有免费额度可用。

如果你使用 Anthropic Claude：需要获取 Claude API Key。访问 https://www.anthropic.com/api-keys 创建。

如果你使用 Ollama（本地模型）：需要下载 Ollama 并pull模型。命令：ollama pull llama3.1

如果你使用 OpenRouter（多模型聚合）：需要获取 OpenRouter API Key。访问 https://openrouter.ai/ 创建。价格相对便宜，支持多种模型。

三、Mac 系统安装教程

macOS 是 Hermes Agent 支持最好的平台，也是推荐开发者的首选。以下是完整的安装步骤。

3.1 通过 Homebrew 一键安装（推荐）

如果你使用 macOS 并且已经安装了 Homebrew，最简单的方式是一键安装：

打开终端，输入以下命令：

# 安装 Hermes Agent brew install hermes-ai  # 或者通过 uv 安装 uv pip install -x "hermes-agent"

安装完成后，运行 hermes --version 确认安装成功。

3.2 手动安装（详细步骤）

如果一键安装出现问题，我们可以手动安装。以下是详细步骤：

第一步：克隆项目仓库。打开终端，进入你想存放项目的目录，输入：

cd ~/Projects git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent

第二步：创建虚拟环境。使用 uv 创建独立的 Python 环境：

uv venv source .venv/bin/activate uv pip install -e ".[cli]"

这行命令中的 .[cli] 表示安装 CLI 所需的依赖。如果你想安装所有依赖，可以使用 .[full]。

第三步：初始化配置。运行 hermes setup 向导：

hermes setup

这个向导会引导你完成：选择 LLM 提供商、填入 API Key、配置默认工具集、设置基础偏好。

3.3 通过 Docker 安装

如果你不想直接安装 Python 环境，Docker 方式也是一个选择：

第一步：拉取 Docker 镜像：

docker pull nousresearch/hermes-agent:latest

第二步：运行容器：

docker run -it \   --volume ~/.hermes:/root/.hermes \   --volume ~/.aws:/root/.aws \   --network host \   nousresearch/hermes-agent:latest

注意：第一次运行时会提示你进行初始配置，和手动安装一样。

3.4 启动与验证

安装完成后，输入以下命令启动 Hermes Agent：

hermes chat

如果一切正常，你应该会看到类似以下的输出：

🦁 Hermes Agent v1.0.0 > 你好！我是你的 AI 助手。有什么我可以帮助你的吗？

恭喜！你已经成功安装了 Hermes Agent。

四、Windows 系统安装教程

Windows 原生并不支持 Hermes Agent，需要通过 WSL2（Windows Subsystem for Linux 2）来运行。以下是完整步骤。

4.1 启用 WSL2

如果你的 Windows 11 已经启用了 WSL2，可以跳过这一步。

第一步：启用"适用于 Linux 的 Windows 子系统"。以管理员身份打开 PowerShell，输入：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

第二步：启用"虚拟机平台"。继续在 PowerShell 中输入：

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

第三步：重启电脑。

第四步：设置 WSL2 为默认版本。打开 PowerShell，输入：

wsl --set-default-version 2

4.2 安装 Linux 发行版

打开 Microsoft Store，搜索"Ubuntu"，安装 Ubuntu 22.04 LTS 或更高版本。

安装完成后，第一次打开 Ubuntu 时会提示你创建用户和密码。这个用户名和密码仅用于 Ubuntu 系统，和 Windows 账户无关。

4.3 在 WSL2 中安装 Hermes Agent

打开 Ubuntu 终端，按照 Linux 的安装步骤进行。这一部分将在下一节详细讲解。

4.4 推荐的替代方案：使用 OpenClaw

如果你觉得 WSL2 安装太复杂，我推荐你尝试 OpenClaw。这是另一个优秀的 AI Agent 框架，对 Windows 支持更好，而且内置了飞书、微信等中国用户常用平台的集成。

OpenClaw 的安装非常简单：

# 以管理员身份打开 PowerShell irm https://get.openclaw.ai | iex

关于 OpenClaw 的详细使用，可以参考官方文档。

五、Linux 系统安装教程

Linux 是 Hermes Agent 支持最完美的平台，也是生产环境部署的首选。以下是 Ubuntu/Debian 系统的安装步骤。

5.1 系统更新与依赖安装

第一步：更新系统包。打开终端，输入：

sudo apt update && sudo apt upgrade -y

第二步：安装必要依赖：

sudo apt install -y git curl build-essential

5.2 安装 uv

Hermes Agent 推荐使用 uv 作为包管理器。安装命令：

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

安装完成后，将 uv 添加到环境变量：

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

验证安装：uv --version

5.3 克隆与安装 Hermes Agent

第一步：克隆项目：

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

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

uv venv source .venv/bin/activate uv pip install -e ".[cli]"

5.4 初始化配置

运行设置向导：

hermes setup

按照提示进行配置。选择你想要的模型提供商，填入 API Key，然后选择默认工具集。

5.5 验证安装

输入以下命令验证：

hermes --version hermes doctor

如果一切正常，hermes doctor 会显示环境检查结果。

六、基础配置指南

安装完成后，正确的配置可以让你更好地使用 Hermes Agent。以下是重要配置项的详细说明。

6.1 配置 API Key

你可以通过以下几种方式配置 API Key：

方式一：通过环境变量：

export OPENAI_API_KEY=sk-your-key-here export ANTHROPIC_API_KEY=sk-ant-your-key-here

方式二：通过 hermes config 命令：

hermes config set OPENAI_API_KEY sk-your-key-here hermes config set ANTHROPIC_API_KEY sk-ant-your-key-here

方式三：直接编辑配置文件。配置文件位于 ~/.hermes/config.yaml：

api_keys:   openai: sk-your-key-here   anthropic: sk-ant-your-key-here

6.2 选择默认模型

你可以通过以下命令设置默认模型：

hermes config set provider.name openai hermes config set provider.model gpt-4o

常用模型配置示例：

OpenAI GPT-4o：hermes chat --model gpt-4o

Anthropic Claude：hermes chat --model anthropic/claude-3.5-sonnet-20241002

Ollama 本地模型：hermes chat --model ollama/llama3.1

6.3 配置工具集

Hermes Agent 内置了 17 个工具集。你可以通过以下命令查看可用工具集：

hermes tools

你可以在配置文件中指定默认使用的工具集：

toolsets:   - web   - terminal   - file   - browser

如果你想使用特定工具集启动：

hermes chat --toolsets "web,terminal"

6.4 配置终端后端

Hermes Agent 支持多种终端运行方式：

本地终端（默认）：

hermes config set terminal.backend local

Docker 方式：

hermes config set terminal.backend docker hermes config set terminal.docker_image python:3.11-slim

SSH 远程：

在 ~/.hermes/.env 中配置：

TERMINAL_SSH_HOST=my-server.example.com TERMINAL_SSH_USER=myuser TERMINAL_SSH_KEY=~/.ssh/id_rsa

6.5 配置 SOUL 人格

Hermes Agent 最有意思的功能之一是通过 SOUL.md 定义 Agent 的人格。你可以在 ~/.hermes/SOUL.md 中定义：

# 你是谁  你是一个专业的 AI 助手，善于帮助用户完成各种任务。  ## 你的特点  - 回答简洁明了 - 注重效率 - 喜欢用代码解决问题  ## 用户偏好  用户喜欢简洁的回答，不喜欢废话。

七、进阶使用技巧

安装和配置完成后，以下这些进阶技巧可以让你更好地使用 Hermes Agent。

7.1 创建自定义技能

Hermes Agent 可以让你创建自定义技能。创建一个技能文件放在 ~/.hermes/skills/ 目录下：

# 技能名称 我的技能  ## 描述 这是一个用于xxx的技能  ## 触发词 我的技能 执行xxx  ## 代码 def execute(context):     # 在这里编写你的技能逻辑     return "执行结果"

7.2 多会话管理

恢复指定会话：

hermes chat -c "项目名"

查看会话列表：

hermes sessions list

删除会话：

hermes sessions delete "会话名"

7.3 快速命令配置

你可以在配置文件中添加自定义快捷命令：

quick_commands:   status:     type: exec     command: systemctl status hermes-agent   gpu:     type: exec     command: nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader

7.4 配置多个性格

你可以在不同场景下切换不同性格：

personalities:   helpful: "You are a helpful, friendly AI assistant."   kawaii: "You are a kawaii assistant! Use cute expressions!"   code: "You are a coding expert. Provide efficient solutions."

使用特定性格启动：

hermes chat --persona code

7.5 上下文压缩

当上下文过长时，可以启用压缩功能：

compression:   enabled: true   threshold: 0.50   summary_model: "google/gemini-3-flash-preview"

这会在上下文达到 50% 时自动压缩，保留关键信息。

7.6 与飞书集成

Hermes Agent 可以接入飞书平台。首先创建一个飞书应用，获取 App ID 和 App Secret。然后配置：

在 ~/.hermes/config.yaml 中：

feishu:   app_id: your-app-id   app_secret: your-app-secret

重启 Hermes Agent 后，即可通过飞书与 Agent 对话。

八、常见问题与解决方案

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

8.1 安装常见问题

问题一：uv 命令未找到

这通常是因为 uv 没有添加到环境变量。解决方法：

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

问题二：Python 版本过低

Hermes Agent 需要 Python 3.10+。检查版本：

python3 --version

如果版本过低，使用 uv 安装新版本：

uv python install 3.11 uv python list

问题三：依赖安装失败

有时依赖安装会因为网络问题失败。可以尝试使用国内源：

export UV_PYTHON_DOWNLOAD_KEY=your-key uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e ".[cli]"

8.2 运行时常见问题

问题一：API Key 无效

如果遇到"API Key 无效"的错误，重新运行 hermes setup：

hermes setup

在向导中重新填入 API Key。

问题二：Gateway 启动失败

如果看到"Gateway 启动失败"的错误，可能是端口被占用：

# 检查端口占用 lsof -i :8000  # 如果有进程占用，杀掉它 kill -9 <PID>

问题三：Ollama 连接失败

如果使用 Ollama 本地模型，确保服务已启动：

# 启动 Ollama ollama serve  # 测试模型 ollama list

8.3 使用常见问题

问题一：工具集不工作

检查工具集是否启用：

hermes tools

在配置文件中添加需要的工具集。

问题二：响应速度慢

可以尝试以下优化：使用更快的模型、启用上下文压缩、减少工具集数量。

问题三：上下文丢失

确保 SOUL.md 文件存在。检查配置文件中的记忆设置是否正确。

九、总结与下一步

恭喜你！看到这里，你已经掌握了 Hermes Agent 的完整安装和配置。这份万字指南涵盖了：

首先是安装前准备：系统要求、必要软件检查、API Key 准备。其次是三大平台安装：macOS、 Windows（WSL2）、Linux 的完整步骤。然后是基础配置：API Key、模型选择、工具集配置。接着是进阶使用：自定义技能、多会话管理、快速命令等。最后是常见问题：安装和运行中的问题解决方案。

下一步你可以做什么：

如果你是开发者，可以去 GitHub 阅读源码，了解 Hermes Agent 的工作原理。

如果你是产品经理，可以尝试搭建一个 AI 工作台，体验 Agent 的产品形态。

如果你是普通用户，可以从 hermes chat 开始，体验 AI 助手的功能。

Hermes Agent 是一个快速迭代的项目，建议关注 GitHub 获取最新动态：https://github.com/NousResearch/hermes-agent

如果你在安装过程中遇到任何问题，欢迎在评论区留言，我会尽力帮你解决。