Hermes Agent 下载安装常见问题汇总（小白必看）

想用 Hermes Agent，第一步就是安装。但很多人卡在这一步——命令敲不对、环境不匹配、依赖装不上。本文汇总了最常见的安装问题及解决方案，纯小白向。

安装前要先确认什么

在开始之前，先确认你的操作系统和硬件：

• Windows：需要 WSL2（Linux 子系统），不建议原生 Windows
• macOS：支持 Apple Silicon（M1/M2/M3）和 Intel 芯片
• Linux：主流发行版都可以，Ubuntu/Debian 最省事

打开终端，输入以下命令查看系统：

# 查看操作系统
cat /etc/os-release

# 查看 CPU 架构
uname -m
# x86_64 = Intel/AMD 64位
# arm64  = Apple Silicon 或 ARM

如果显示 x86_64，说明是 64 位系统，可以继续安装。

WSL2 安装（Windows 用户必看）

Windows 用户需要先装 WSL2，这是第一步。

方法一：命令一键安装

以管理员身份打开 PowerShell 或命令提示符，运行：

wsl --install

安装完成后需要重启电脑。重启后会自动启动 Ubuntu，此时设置用户名和密码（记住这个密码，后面 sudo 命令要用）。

方法二：手动安装（更稳定）

如果方法一失败，试试手动安装：

1. 启用 Hyper-V 和虚拟机平台（控制面板 → 程序 → 启用 Windows 功能）
2. 下载 Ubuntu 22.04 LTS 镜像
3. 用 Hyper-V 新建虚拟机，挂载镜像安装

安装后必做

# 切换到 Linux 环境
wsl -d Ubuntu

# 更新软件源
sudo apt update && sudo apt upgrade -y

# 安装基础工具
sudo apt install curl git build-essential -y

Hermes Agent 怎么装

确认环境准备好了，就可以安装 Hermes。

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

curl -fsSL https://get.hermes-agent.dev | bash

这个命令会自动检测你的系统环境，安装所有依赖，创建配置文件。整个过程大约 2-3 分钟。

方法二：手动安装

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

# 进入目录
cd hermes-agent

# 创建虚拟环境（避免污染系统 Python）
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -e .

# 初始化配置
hermes setup

验证是否安装成功

hermes --version

如果显示版本号（如 hermes v1.x.x），说明安装成功了。

常见报错及解决

报错一：python3: command not found

这是最常见的报错。Linux/macOS 默认不一定装了 Python，或者装了但没加入 PATH。
解决：

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

# macOS
brew install python3

# 验证
python3 --version

报错二：pip install 报权限错误

错误信息：Permission denied 或 externally-managed-environment

这是 Python 3.11+ 的新特性，不允许直接 pip 到系统环境。
解决：用虚拟环境

python3 -m venv venv
source venv/bin/activate
pip install -e .

以后每次使用 Hermes，先运行 source venv/bin/activate 激活虚拟环境。

报错三：SSL 证书错误

错误信息：SSL: CERTIFICATE_VERIFY_FAILED
解决：

# macOS 需要安装证书
/Applications/Python\ 3.x/Install\ Certificates.command

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

报错四：WSL2 安装 Ubuntu 卡在 0%

Windows 用户常见问题。
解决：

1. 手动下载 Ubuntu 镜像
2. 用 WSL 命令导入：

wsl --import Ubuntu D:\WSL\Ubuntu .\ubuntu.tar.gz
wsl -d Ubuntu

报错五：依赖安装失败（timeout/404）

可能是网络问题，国内访问 GitHub/PyPI 不稳定。
解决：换国内源

# 临时换源
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple some-package

# 永久换源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后怎么配置

安装成功后，还需要配置 API 密钥才能真正使用。

1. 获取 API 密钥

Hermes 支持多种模型提供方，推荐先从 MiniMax 开始（国内可直接访问）：

1. 访问 MiniMax 开放平台：https://platform.minimaxi.com
2. 注册账号（可用手机号）
3. 进入控制台 → API 密钥 → 创建新密钥
4. 复制密钥（格式类似 ab123...xyz）

2. 配置密钥

有两种方式：
方式一：环境变量（推荐）

export MINIMAX_API_KEY="你的密钥"
export MINIMAX_BASE_URL="https://api.minimaxi.com/v1"

方式二：配置文件

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

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

3. 验证配置

hermes doctor

这个命令会检查所有依赖、配置、连接状态。如果显示 ✓ All checks passed，就可以开始使用了。

首次启动

配置完成后，启动 Hermes：

hermes

如果是第一次运行，会提示你做一些初始设置（用户名、使用场景等），按提示操作即可。

相关配置优化

让配置永久生效

上面用 export 设置的环境变量重启后会失效。如果想永久生效：

# 把配置写入 ~/.bashrc（每次打开终端自动加载）
echo 'export MINIMAX_API_KEY="你的密钥"' >> ~/.bashrc
echo 'export MINIMAX_BASE_URL="https://api.minimaxi.com/v1"' >> ~/.bashrc

# 使配置立即生效
source ~/.bashrc

更新 Hermes 版本

# 查看当前版本
hermes --version

# 更新到最新版本
hermes update

# 或者手动更新
cd hermes-agent
git pull
pip install -e .

常见问题

Q：WSL2 和虚拟机有什么区别？
WSL2 是 Windows 内置的 Linux 子系统，性能比虚拟机好，和 Windows 文件互通也方便。推荐 WSL2。

Q：安装要多久？
网络正常的情况下，10-20 分钟可以搞定。大部分时间在下载依赖。

Q：电脑配置低能跑吗？
Hermes 本身是调 API 的，对本地硬件要求不高。只要能跑 Python 3.10+ 就行。

Q：可以同时用多个模型吗？
可以。在 config.yaml 里配置多个 provider，用 --model 参数切换。

Q：卸载怎么操作？
删除安装目录和配置目录即可：rm -rf ~/hermes-agent ~/.hermes

安装问题解决了，下一步就是开始用起来。建议先从简单的问题开始测试，熟悉之后再尝试复杂任务。