Hermes Agent 安装指南 - 跨平台详细教程

快速安装

使用官方安装脚本一键安装（适用于 macOS 和 Linux）：

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

Windows 用户请查看下方的 Windows 详细安装步骤

🍎 macOS

🪟 Windows

🐧 Linux

🍎 macOS 安装指南

支持 macOS 10.15 (Catalina) 及更高版本。推荐 macOS 12+ 以获得最佳体验。

系统要求

✓ macOS 10.15+ (Intel 或 Apple Silicon)
✓ Python 3.11 或更高版本
✓ 至少 4GB 可用内存
✓ 网络连接（用于下载模型和工具）

💡

提示：Apple Silicon (M1/M2/M3) 用户无需额外配置，安装脚本会自动检测架构。

安装步骤

安装 Homebrew（如尚未安装）

Homebrew 是 macOS 的包管理器，用于安装 Python 等依赖。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装 Python 3.11+

使用 Homebrew 安装最新版 Python：

brew install python@3.11

✓

验证安装：python3 --version 应显示 3.11.x 或更高版本

安装 Hermes Agent

运行官方安装脚本：

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

或手动安装：

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

配置环境变量

将 Hermes 添加到系统 PATH（根据你的 shell 选择）：

Bash (默认):

echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Zsh (macOS Catalina+ 默认):

echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

运行设置向导

配置模型提供商和 API 密钥：

hermes setup

💡

向导会引导你配置默认模型、API 密钥等。你也可以稍后使用 hermes model 更改设置。

验证安装

hermes doctor

✓

如果显示所有检查通过，安装成功！运行 hermes 开始交互式会话。

常见问题

问题	解决方案
"command not found: hermes"	检查 PATH 配置，确保 `~/.hermes/bin` 已添加
Python 版本过低	运行 `brew install python@3.11` 升级
权限被拒绝	运行 `chmod +x ~/.hermes/bin/hermes`
Apple Silicon 兼容性问题	确保使用 ARM 版 Python：`brew install python@3.11`

🪟 Windows 安装指南

支持 Windows 10/11。推荐通过 WSL2 (Windows Subsystem for Linux) 或 PowerShell 安装。

系统要求

✓ Windows 10 (build 19041+) 或 Windows 11
✓ Python 3.11 或更高版本
✓ PowerShell 5.1+ 或 Windows Terminal
✓ 至少 4GB 可用内存

⚠️

注意：Windows 原生安装可能遇到路径和权限问题。强烈推荐使用 WSL2 获得最佳体验。

方案 A：WSL2 安装（推荐）

WSL2 提供完整的 Linux 环境，是 Windows 上运行 Hermes 的最佳方式。

安装 WSL2

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

wsl --install

💡

安装完成后重启电脑，然后设置 Ubuntu 用户名和密码。

在 WSL2 中安装 Hermes

打开 WSL2 Ubuntu 终端，运行：

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

或手动安装：

sudo apt update && sudo apt install -y python3-pip git
pip3 install --user hermes-agent

配置 Windows Terminal

推荐使用 Windows Terminal 获得最佳体验：

# 在 Windows Terminal 中设置 WSL2 为默认配置文件
# 设置 → 启动 → 默认配置文件 → Ubuntu (WSL)

⚠️

重要：在 WSL2 中，Hermes 的文件工具访问的是 Linux 文件系统，不是 Windows 文件系统。使用 /mnt/c/ 访问 Windows 磁盘。

方案 B：Windows 原生安装

直接在 Windows PowerShell 或 cmd 中运行。

安装 Python 3.11+

从 python.org 下载并安装 Python。安装时勾选 "Add Python to PATH"。

# 验证安装
python --version
# 应显示 Python 3.11.x 或更高

安装 Git

从 git-scm.com 下载 Git for Windows。

安装 Hermes

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

# 创建安装目录
mkdir $env:USERPROFILE\.hermes
cd $env:USERPROFILE\.hermes

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

# 安装
cd hermes-agent
pip install -e .

配置 PATH

将 Hermes 添加到系统 PATH：

# 添加到用户 PATH
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.hermes\bin", "User")

# 刷新环境变量
$env:Path = [Environment]::GetEnvironmentVariable("Path", "User")

运行设置向导

hermes setup

🔧 Windows / WSL 常见问题与解决方案

以下是 Windows 环境下部署 Hermes 时最常遇到的问题，按排查优先级排列。

问题 1：git clone 连接 GitHub 443 端口超时

WSL 2 默认使用 NAT 网络，无法直接访问 Windows 上的 localhost 代理。

获取 Windows 主机真实 IP

ip route | grep default | awk '{print $3}'

输出类似 172.29.192.1，这就是 Windows 主机 IP。

设置代理（假设端口为 7890）

export http_proxy=http://172.29.192.1:7890
export https_proxy=http://172.29.192.1:7890

确保代理软件开启"允许局域网连接"

Clash for Windows：General → Allow LAN → 开启

Clash Verge：设置 → 网络 → 允许局域网连接 → 开启

V2Ray：配置文件中设置 "allowLan": true

⚠️

常见错误：代理地址指向了 DNS 服务器（如 223.5.5.5）而非主机 IP。请确保用 ip route 获取的是网关地址，不是 DNS 地址。

问题 2：/etc/resolv.conf 被公共 DNS 覆盖

如果 cat /etc/resolv.conf 显示 223.5.5.5 或 8.8.8.8，说明 WSL 的 DNS 配置被手动修改过。

sudo cp /etc/resolv.conf /etc/resolv.conf.bak
sudo rm /etc/resolv.conf
wsl --shutdown
wsl

重启 WSL 后会自动重新生成正确的 resolv.conf。

💡

更可靠的方法：用 ip route | grep default | awk '{print $3}' 获取主机 IP，不依赖 DNS 配置。

问题 3：WSL 重启后 IP 变化，代理失效

在 ~/.bashrc 末尾添加自动配置脚本：

HOST_IP=$(ip route | grep default | awk '{print $3}')
export http_proxy="http://$HOST_IP:7890"
export https_proxy="http://$HOST_IP:7890"
export HTTP_PROXY="http://$HOST_IP:7890"
export HTTPS_PROXY="http://$HOST_IP:7890"

执行 source ~/.bashrc 生效。每次打开终端自动适配新 IP。

问题 4：Python 3.14 版本不兼容

Hermes 要求 Python >=3.11,<3.14。如果系统 Python 是 3.14+，需要降级。

安装 pyenv

sudo apt install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncurses5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
curl https://pyenv.run | bash

配置 pyenv 并安装 Python 3.12

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc
pyenv install 3.12.9

在项目中使用 Python 3.12

cd ~/hermes-agent
pyenv local 3.12.9
rm -rf venv
python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -e .

💡

备选方案：使用 deadsnakes PPA sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.12 python3.12-venv，但可能与系统 Python 冲突，推荐用 pyenv。

问题 5：git config --unset-all 报错 wrong number of arguments

--unset-all 后面只需要跟一个配置键名，不能同时跟值。

git config --global --unset-all user.name
git config --global user.name "你的新名字"

或者直接编辑配置文件 ~/.gitconfig 修改。

⚠️

WSL 与 Windows Git 配置隔离：WSL 的 ~/.gitconfig 和 Windows 的 C:\Users\用户名\.gitconfig 互不影响，请在正确的终端中配置。

问题 6：在 WSL 中执行 wsl 命令报 not found

wsl 是 Windows 命令，在 WSL 内应使用 wsl.exe。不要执行 sudo apt install wsl，那是完全不相关的包。

wsl.exe --version

Windows 特定注意事项

问题	解决方案
Alt+Enter 无法换行	Windows Terminal 拦截了 Alt+Enter，使用 Ctrl+Enter 代替
配置文件 UTF-8 BOM 问题	使用 `hermes config edit` 编辑配置，避免使用记事本保存
WinError 10106 (Winsock)	确保 SYSTEMROOT 环境变量已设置，运行 `$env:SYSTEMROOT` 检查
路径分隔符	在代码中使用正斜杠 `/`，Hermes 会自动处理
网关服务随 SSH 断开	WSL2 需要 `systemd=true` 在 `/etc/wsl.conf` 中

WSL 部署常见问题排查

以下问题在 Windows + WSL2 环境部署 Hermes 时极为常见，按出现频率排序。

🔴

问题 1：git clone 报错 "Failed to connect to github.com port 443: Connection timed out"

原因：WSL2 默认使用 NAT 网络模式，localhost 指向 WSL 自身而非 Windows 主机。如果你在 Windows 上开了代理（Clash / V2Ray 等），WSL 无法直接通过 localhost 访问它。

解决方案：配置 WSL 代理

获取 Windows 主机真实 IP

# 方法 A：通过默认网关（推荐，不受 DNS 影响）
HOST_IP=$(ip route | grep default | awk '{print $3}')
echo $HOST_IP  # 应显示类似 172.x.x.1 的私有 IP

# 方法 B：通过 resolv.conf
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'

⚠️

注意：如果 resolv.conf 中是 223.5.5.5 或 8.8.8.8（公共 DNS），说明该文件被手动覆盖了，请用方法 A 获取 IP。

设置代理环境变量

假设主机 IP 是 172.31.176.1，代理端口是 7890：

export http_proxy=http://172.31.176.1:7890
export https_proxy=http://172.31.176.1:7890

或写入 Git 全局配置：

git config --global http.proxy http://172.31.176.1:7890
git config --global https.proxy http://172.31.176.1:7890

验证代理是否生效

curl -v https://github.com # 应返回 HTTP/2 200

💡

代理端口速查：Clash = 7890，Clash Verge = 7897，V2Ray = 10809，Shadowsocks = 1080，Surge = 6152

🔴

问题 2：代理 IP 正确但仍然超时（代理软件未开启"允许局域网连接"）

原因：代理软件默认只监听 127.0.0.1，不接受来自 WSL 虚拟网络的连接。

解决方案

Clash for Windows：General → Allow LAN → 开启
Clash Verge：设置 → 网络 → 允许局域网连接 → 开启
V2Ray：配置文件中 "allowLan": true

🔴

问题 3：WSL 重启后代理失效（IP 地址变化）

原因：WSL2 每次启动时可能分配不同的虚拟网卡 IP。

解决方案：在 `~/.bashrc` 中添加自动代理配置

# 添加到 ~/.bashrc 末尾
if command -v ip &> /dev/null; then
    HOST_IP=$(ip route | grep default | awk '{print $3}')
    if [ -n "$HOST_IP" ]; then
        export http_proxy="http://$HOST_IP:7890"
        export https_proxy="http://$HOST_IP:7890"
        export HTTP_PROXY="http://$HOST_IP:7890"
        export HTTPS_PROXY="http://$HOST_IP:7890"
    fi
fi

# 生效
source ~/.bashrc

🔴

问题 4：Python 版本不兼容（"requires-python = >=3.11,<3.14"）

原因：Hermes 要求 Python 3.11~3.13，但 Ubuntu 可能安装了 Python 3.14（开发版），导致 pip install -e . 报错。

解决方案：使用 pyenv 安装正确的 Python 版本

# 1. 安装 pyenv 依赖
sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncurses5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

# 2. 安装 pyenv
curl https://pyenv.run | bash

# 3. 配置（添加到 ~/.bashrc 末尾）
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

# 4. 安装 Python 3.12
pyenv install 3.12.9

# 5. 在项目中使用
cd ~/hermes-agent
pyenv local 3.12.9

# 6. 重建虚拟环境并安装
rm -rf venv
python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -e .

🔴

问题 5：git config --global --unset-all 报错 "wrong number of arguments"

原因：命令格式错误。--unset-all 后面只能跟一个配置键名，不能同时跟值。

解决方案

# 正确用法：只跟键名
git config --global --unset-all user.name

# 如需精准删除某个值
git config --global --unset-all user.name --value="John"

# 或直接覆盖设置（更简单）
git config --global user.name "你的新名字"

🔴

问题 6：在 WSL 中执行 wsl --version 报错 "command not found"

原因：wsl 是 Windows 系统命令，WSL Linux 环境中不存在。系统提示的 sudo apt install wsl 是另一个无关的包。

解决方案

# 在 WSL 中调用 Windows 命令需加 .exe 后缀
wsl.exe --version

# 或在 Windows PowerShell 中执行
wsl --version

# 如果已误装无关的 wsl 包，可卸载
sudo apt remove wsl

🔴

问题 7：resolv.conf 被公共 DNS 覆盖，无法获取宿主机 IP

原因：VPN 软件、Docker 或手动修改覆盖了 /etc/resolv.conf，导致其中是 223.5.5.5（阿里 DNS）或 8.8.8.8（Google DNS）而非 WSL 网关。

解决方案

# 不依赖 resolv.conf，直接从路由表获取网关 IP（最可靠）
HOST_IP=$(ip route | grep default | awk '{print $3}')
echo $HOST_IP

# 如需恢复 WSL 自动生成的 resolv.conf
sudo rm /etc/resolv.conf
exit  # 退出 WSL
wsl --shutdown  # 在 PowerShell 中执行
wsl             # 重新进入

# 检查 /etc/wsl.conf 确保自动生成开启
cat /etc/wsl.conf
# 应包含：
# [network]
# generateResolvConf = true

快速诊断清单

遇到网络问题时，按顺序执行以下命令：

# 1. 检查 WSL 能否访问外网
ping 8.8.8.8

# 2. 获取 Windows 主机 IP
ip route | grep default | awk '{print $3}'

# 3. 检查当前代理环境变量
env | grep -i proxy

# 4. 测试代理连通性（替换 IP 和端口）
curl -x http://$(ip route | grep default | awk '{print $3}'):7890 https://github.com -I

# 5. 检查 Git 代理配置
git config --global --list | grep -i proxy

🐧 Linux 安装指南

支持 Ubuntu 20.04+, Debian 11+, Fedora 35+, Arch Linux 等主流发行版。

系统要求

✓ Linux 内核 5.4+
✓ Python 3.11 或更高版本
✓ pip 包管理器
✓ Git
✓ 至少 4GB 可用内存

Ubuntu / Debian 安装

更新系统包

sudo apt update && sudo apt upgrade -y

安装依赖

sudo apt install -y python3.11 python3.11-pip python3.11-venv git curl wget

💡

如果仓库中没有 Python 3.11，使用 deadsnakes PPA：sudo add-apt-repository ppa:deadsnakes/ppa

安装 Hermes

使用官方安装脚本：

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

或手动安装：

git clone https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent
cd ~/.hermes/hermes-agent
python3.11 -m pip install --user -e .

配置 PATH

将 Hermes 添加到 PATH（根据你的 shell）：

Bash:

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

Zsh:

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

Fish:

set -Ux PATH $HOME/.local/bin $HOME/.hermes/bin $PATH

运行设置向导

hermes setup

Fedora / RHEL / CentOS 安装

安装依赖

sudo dnf install -y python3.11 python3.11-pip git curl

安装 Hermes

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

Arch Linux 安装

安装依赖

sudo pacman -S python python-pip git curl

安装 Hermes

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

Linux 常见问题

问题	解决方案
pip 安装权限错误	使用 `--user` 标志或创建虚拟环境
Python 版本过低	使用 pyenv 或发行版特定 PPA 安装 Python 3.11+
网关服务无法后台运行	启用 systemd linger：`sudo loginctl enable-linger $USER`
SSL 证书错误	更新 ca-certificates：`sudo apt install ca-certificates`
找不到 hermes 命令	检查 `~/.local/bin` 是否在 PATH 中

安装后配置

1. 配置模型提供商

选择你要使用的 AI 模型提供商：

hermes model

2. 常用命令

命令	说明
`hermes`	启动交互式会话
`hermes chat -q "问题"`	单次查询模式
`hermes doctor`	检查安装状态
`hermes config edit`	编辑配置文件
`hermes tools`	管理工具集
`hermes skills list`	查看已安装技能
`hermes update`	更新到最新版本

3. 配置 API 密钥

编辑 ~/.hermes/.env 文件添加你的 API 密钥：

# OpenRouter
OPENROUTER_API_KEY=your_key_here

# Anthropic
ANTHROPIC_API_KEY=your_key_here

# OpenAI
OPENAI_API_KEY=your_key_here

# DeepSeek
DEEPSEEK_API_KEY=your_key_here

4. 关闭终端后重新进入 Hermes

关闭终端后再次使用 Hermes，只需重新激活虚拟环境：

# 打开windows终端，输入命令进入linux终端
wsl

# 然后进入项目目录
cd ~/hermes-agent

# 激活虚拟环境（看到提示符前出现 (venv) 即成功）
source venv/bin/activate

# 开始使用
hermes chat

💡

一键快捷方式：在 ~/.bashrc 中添加别名，之后只需输入 hermes-go chat 即可直接进入：

echo 'alias hermes-go="cd ~/hermes-agent && source venv/bin/activate && hermes"' >> ~/.bashrc
source ~/.bashrc

# 之后使用
hermes-go chat

⚠️

验证虚拟环境：运行 which python，如果显示 ~/hermes-agent/venv/bin/python 说明已正确激活。如果 hermes 命令找不到，重新执行 pip install -e . 安装。

获取帮助

📖 官方文档：hermes-agent.nousresearch.com/docs
💬 GitHub Discussions：讨论区
🐛 提交 Issue：GitHub Issues
🚀 项目主页：github.com/NousResearch/hermes-agent

快速安装

🍎 macOS 安装指南

系统要求

安装步骤

安装 Homebrew（如尚未安装）

安装 Python 3.11+

安装 Hermes Agent

配置环境变量

运行设置向导

验证安装

常见问题

🪟 Windows 安装指南

系统要求

方案 A：WSL2 安装（推荐）

安装 WSL2

在 WSL2 中安装 Hermes

配置 Windows Terminal

方案 B：Windows 原生安装

安装 Python 3.11+

安装 Git

安装 Hermes

配置 PATH

运行设置向导

🔧 Windows / WSL 常见问题与解决方案

问题 1：git clone 连接 GitHub 443 端口超时

获取 Windows 主机真实 IP

设置代理（假设端口为 7890）

确保代理软件开启"允许局域网连接"

问题 2：/etc/resolv.conf 被公共 DNS 覆盖

问题 3：WSL 重启后 IP 变化，代理失效

问题 4：Python 3.14 版本不兼容

安装 pyenv

配置 pyenv 并安装 Python 3.12

在项目中使用 Python 3.12

问题 5：git config --unset-all 报错 wrong number of arguments

问题 6：在 WSL 中执行 wsl 命令报 not found

Windows 特定注意事项

WSL 部署常见问题排查

解决方案：配置 WSL 代理

获取 Windows 主机真实 IP

设置代理环境变量

验证代理是否生效

解决方案

解决方案：在 ~/.bashrc 中添加自动代理配置

解决方案：使用 pyenv 安装正确的 Python 版本

解决方案

解决方案

解决方案

快速诊断清单

🐧 Linux 安装指南

系统要求

Ubuntu / Debian 安装

更新系统包

安装依赖

安装 Hermes

配置 PATH

运行设置向导

Fedora / RHEL / CentOS 安装

安装依赖

安装 Hermes

Arch Linux 安装

安装依赖

安装 Hermes

Linux 常见问题

安装后配置

1. 配置模型提供商

2. 常用命令

3. 配置 API 密钥

4. 关闭终端后重新进入 Hermes

获取帮助

解决方案：在 `~/.bashrc` 中添加自动代理配置