养马、养马、养马

写在前面

当你兴冲冲地复制官方安装Hermes Agent命令：

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

却发现终端卡住了，或者报出一连串看不懂的错误。

别急。这篇文章就是为你准备的——一份从零开始的完整安装教程，包含 Windows 环境准备、WSL 安装、Hermes Agent 安装，以及我们遇到的所有“坑”和填坑方法。全程实测，保证你能跑通。

---

第一部分：在 Windows 上安装 WSL

Hermes Agent 官方支持 Linux 和 macOS。对于 Windows 用户，最稳妥的方式是使用 WSL 2（Windows Subsystem for Linux）。

1.1 启用 WSL

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

wsl --install

这个命令会自动：

• 启用 WSL 功能

• 安装默认的 Ubuntu 发行版

• 设置 WSL 2 为默认版本

等待下载和安装完成，然后重启电脑。

1.2 常见错误：已存在具有所提供名称的分发

如果你之前安装过 WSL 或者 Ubuntu，可能会遇到：

错误代码: Wsl/InstallDistro/Service/RegisterDistro/ERROR_ALREADY_EXISTS

原因：系统中已存在名为 Ubuntu 的发行版。

解决方法：

1. 查看已有发行版：wsl --list --verbose

2. 注销旧版：wsl --unregister Ubuntu

3. 重新安装：wsl --install

或者，你也可以保留旧的，安装一个新的并指定名称：

wsl --install -d Ubuntu --name HermesUbuntu

1.3 启动 Ubuntu 并设置用户

重启后，在开始菜单找到 “Ubuntu” 并打开。首次启动会提示创建用户名和密码——记住它们，后续 sudo 操作会用到。

---

第二部分：安装 Hermes Agent

现在进入真正的挑战。我们以下载的 install.sh 脚本为核心，逐步解决网络、依赖、权限等问题。

2.1 为什么直接 curl | bash 会卡住？

官方的“一行命令”看似方便，但实际运行时，脚本内部会询问你是否安装 ripgrep 和 ffmpeg。由于管道操作符 | 把脚本内容直接喂给 bash，导致 键盘输入无法传递，终端就卡死在交互提示上。

解决方案：分两步走，先下载脚本，再执行。

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

2.2 网络问题大集合

在国内网络环境下，你会遇到三类网络错误：

🔹 类型一：apt 源超时 / Bad header

错误示例：

Err:4 http://archive.ubuntu.com/ubuntu noble-updates/main amd64 libasound2-data all 1.2.11-1ubuntu0.1
Bad header line Bad header data

原因：Ubuntu 默认源在国外，连接不稳定。

解决：更换为国内镜像源（以清华源为例）：

sudo sed -i 's/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list
sudo apt update

🔹 类型二：git clone 失败

错误示例：

fatal: unable to access 'https://github.com/...': Failed to connect to github.com port 443: Connection timed out

原因：GitHub 直连超时。安装脚本内部会执行 git clone，但没走代理。

解决：手动使用 GitHub 镜像克隆仓库：

git clone https://ghfast.top/https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent
cd ~/.hermes/hermes-agent
bash scripts/install.sh   # 重新运行剩余安装步骤

其他可用镜像：https://mirror.ghproxy.com/

🔹 类型三：PyPI 下载超时

错误示例：

error: Request failed after 3 retries: Failed to fetch: https://pypi.org/simple/jinja2/
Caused by: operation timed out

原因：Hermes 使用 uv 管理 Python 包，默认从官方 PyPI 下载，同样遭遇网络问题。

解决：为 uv 配置国内镜像源。推荐方法（永久生效）：

echo 'export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"' >> ~/.bashrc
source ~/.bashrc

2.3 关于 sudo 的“坑”

在执行 sudo apt update 时，如果你看到：

已在此计算机上禁用 Sudo。若要启用它，请转到“设置”应用中的 Developer Settings page

别慌。这通常是因为你在 Windows 的 PowerShell 或 CMD 里运行了 Linux 命令。请确保你在 WSL 的 Ubuntu 终端中执行所有 sudo、apt、hermes 等命令。

2.4 安装过程中的交互选择

当脚本询问 Install ripgrep for faster file search ffmpeg for TTS voice messages? [Y/n] 时：

• 如果你想完全安装，输入 y（前提是 apt 源已换成国内源，否则会再次卡住）。

• 如果你只想快速体验核心功能，输入 n 跳过。之后可以手动安装：sudo apt install ripgrep ffmpeg。

2.5 安装成功？不，还有最后一步：command not found

即使安装脚本最终显示成功，你输入 hermes --version 依然可能提示 command 'hermes' not found。

原因：可执行文件虽然装好了，但它的路径不在系统的 PATH 环境变量中。

查找文件位置：

find ~ -name "hermes" -type f 2>/dev/null

典型输出：

/home/你的用户名/.hermes/hermes-agent/hermes
/home/你的用户名/.hermes/hermes-agent/venv/bin/hermes

正确的路径是虚拟环境下的 bin 目录，即 /home/你的用户名/.hermes/hermes-agent/venv/bin。

添加到 PATH：

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

现在再试 hermes --version，应该能看到版本号（如 hermes 0.15.1）。

2.6 终极备用方案：直接用 Python 运行

如果无论如何 hermes 命令都不能用，可以使用 Python 模块方式运行：

python -m hermes --version
python -m hermes setup   # 配置
python -m hermes         # 启动

这个方式绕过了命令链接问题，100% 可靠。

---

好了安装到此结束，容我缓缓，后面再整理启动配置的流程

以上都是本人针对安装过程中遇到问题经过AI整理的总结，如果本文对你有帮助，欢迎点赞、收藏、转发。也欢迎在评论区留下你在安装过程中遇到的其他问题，我会尽力解答。

本文基于 NousResearch/hermes-agent 最新版（0.15.1）实测。后续版本如有变化，请以官方文档为准。