Hermes Agent 安装教程：Windows/Linux/macOS 详细图解

很多新手第一次安装 Hermes Agent 不知道从哪里下手，本文用最详细的步骤图解，手把手教你从零安装 Hermes Agent，包教包会。

安装前准备

在安装 Hermes Agent 之前，先确认你的电脑满足以下条件：

• 操作系统：Windows 10/11（需 WSL2）、macOS 10.15+、Linux Ubuntu 20.04+
• Python 3.10 或更高版本
• 有 AI 模型的 API Key（可选，最初可以用免费额度测试）

# 先确认 Python 版本，打开终端输入：
python3 --version
# 如果显示 3.10 以上就 OK
# 如果显示没装 Python，继续往下看安装方法

Windows 用户：先装 WSL2

Windows 不支持直接安装 Hermes，需要先装 WSL2（Windows Subsystem for Linux）：

# 1. 以管理员身份打开 PowerShell，运行：
wsl --install

# 2. 等待安装完成（大约 5-10 分钟），期间可能会重启一次

# 3. 重启后会自动启动 Ubuntu，设置你的用户名和密码（密码要记住，后面 sudo 用）

# 4. 进入 Ubuntu 后，运行：
sudo apt update && sudo apt upgrade -y

如果 wsl --install 报错，用方法二手动安装：

# 1. 打开 PowerShell（管理员），依次运行：
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

# 2. 重启电脑

# 3. 下载 Ubuntu 22.04：
wsl --install -d Ubuntu-22.04

macOS / Linux 用户

这两个系统直接跳过 WSL2 步骤，从第 2 步开始。

# 先装依赖（macOS 用 brew，Linux 用 apt）
# macOS:
brew install python3 git

# Ubuntu/Debian:
sudo apt install python3 python3-venv python3-pip git curl -y

正式安装 Hermes Agent（所有系统通用）

方法一：一键安装脚本（推荐）

# 在终端运行：
curl -fsSL https://get.hermes-agent.dev | bash

脚本会自动检测你的系统，安装所有依赖，生成配置文件。整个过程 2-5 分钟，无需人工干预。

方法二：手动安装

# 1. 克隆 GitHub 仓库：
git clone https://github.com/nousresearch/hermes-agent.git
cd hermes-agent

# 2. 创建 Python 虚拟环境（强烈推荐）：
python3 -m venv venv
source venv/bin/activate

# 3. 安装依赖：
pip install -e .

# 4. 运行初始化向导：
hermes setup

运行 hermes setup 后会提示你输入 API Key，按照提示操作即可。

配置 API Key

安装完成后，还需要配置 AI 模型的 API Key 才能真正使用。有两种方式：

方式一：配置文件（永久生效）

# 编辑配置文件：
nano ~/.hermes/config.yaml

# 填入以下内容：
provider: minimax-cn
model: MiniMax-M2.7-highspeed
api_key: 你的API密钥

方式二：环境变量（临时）

# 临时设置（关闭终端后失效）：
export MINIMAX_API_KEY="你的API密钥"
export MINIMAX_BASE_URL="https://api.minimaxi.com/v1"

# 永久生效写到 ~/.bashrc：
echo 'export MINIMAX_API_KEY="你的API密钥"' >> ~/.bashrc
source ~/.bashrc

验证安装是否成功

# 运行诊断命令：
hermes doctor

如果看到类似 ✓ All checks passed 的输出，说明安装成功，Hermes Agent 可以正常使用。

启动 Hermes Agent

# 在终端运行：
hermes

会看到一个欢迎界面和输入框，在里面输入你想让 AI 完成的任务即可。

安装常见报错及解决

报错：python3: command not found

# Ubuntu/Debian:
sudo apt install python3 python3-venv python3-pip -y

# macOS:
brew install python3

报错：Permission denied / externally-managed-environment

# 这是 Python 3.11+ 的保护机制，必须用虚拟环境：
python3 -m venv venv
source venv/bin/activate
pip install -e .

报错：SSL 证书错误

# Linux 下：
pip install certifi
export SSL_CERT_FILE=$(python3 -c "import certifi; print(certifi.where())")

# macOS 下：
/Applications/Python\ 3.x/Install\ Certificates.command

报错：wsl –install 卡住不动

手动下载 Ubuntu 镜像，然后用 wsl --import 导入，步骤稍复杂，建议直接搜索”WSL2 手动安装 Ubuntu”有详细图文教程。

更新 Hermes Agent

# 进入安装目录：
cd ~/hermes-agent

# 拉取最新代码：
git pull

# 更新依赖：
pip install -e .

# 验证版本：
hermes --version

卸载 Hermes Agent

# 删除安装目录和配置目录：
rm -rf ~/hermes-agent ~/.hermes

# 如果用了虚拟环境，删除 venv：
rm -rf ~/hermes-agent/venv

常见问题

Q：安装要多久？
网络正常的话，10-20 分钟。WSL2 用户可能稍长，主要时间在下载依赖。

Q：API Key 哪里申请？
推荐 MiniMax（国内可直接访问）：platform.minimaxi.com，注册后控制台创建 API 密钥。

Q：可以不安 WSL2 直接在 Windows 原生跑吗？
目前不行，Hermes Agent 需要 Linux 环境。WSL2 是最轻量的方案，必须装。

Q：多台电脑可以用同一个配置吗？
可以。把 ~/.hermes/config.yaml 复制到其他电脑的相同路径即可，API Key 可以用同一个。