Hermes Agent安装踩坑与解决方案

网上那些手把手安装的教程看起来都很顺畅，截图全是成功界面，仿佛一键搞定。但真实环境远没有那么理想——从第一步开始就可能遇到各种意想不到的卡壳。大部分人都是把这些出错信息丢给DeepSeek或Kimi，一步步问、一步步修，反复折腾才跑通。这里把实际踩过的坑做个复盘总结，尤其把那些容易被忽略的细节都摆出来。

一、环境准备：WSL2 安装

在 Windows 上装 Hermes，原生并不支持，所以推荐先装一个 Ubuntu 虚拟机，然后在虚拟机里安装 hermes。Windows 这边要先开启 WSL2（Windows Subsystem for Linux 2），它相当于在 Windows 里加一层 Linux 兼容层——注意这不是装第二个操作系统，而是给 Windows 装一个插件。

系统要求

Windows 11 任意版本，或者 Windows 10 需要 ≥ 2004 版本。

启用 WSL2

以管理员身份打开 PowerShell，依次执行以下命令：

# 启用 WSL
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
# 启用虚拟机平台（WSL2 必需）
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

执行完后重启电脑。

然后设置 WSL 默认版本为 2：

wsl --set-default-version 2
# 查看当前状态，确认没有报错
wsl --status

如果提示需要更新 WSL2 Linux 内核，就去下载并安装 wsl_update_x64.msi。

安装完更新包后，再次执行上面的命令确认一切正常。

二、常见安装问题及解决方案

以管理员身份打开 PowerShell，输入命令 wsl --install 开始安装。但这里往往就是第一个坎。

问题1：提示无效的 install，需要升级 wsl

更新wsl异常

wsl --update
正在检查更新...
正在下载更新...
正在安装更新...
这个处理器类型不支持该安装程序包。请与产品供应商联系。

这个提示说明当前 Windows 系统架构（32位/64位/ARM）与 WSL2 更新包不匹配，或者 CPU 不支持虚拟化。

解决办法：手动下载 wsl_update_x64.msi 并双击安装，完成后重启电脑。再执行：

wsl --set-default-version 2
wsl --install -d Ubuntu-20.04

等待部署完成，重新启动电脑。

问题2：win10安装Ubuntu异常错误代码: 0x80072ee7

正在下载: Ubuntu 20.04 LTS
安装过程中间出现错误。分发名称: 'Ubuntu 20.04 LTS' 错误代码: 0x80072ee7

这个错误通常是因为网络或镜像源问题导致下载失败。可以提前手动下载指定版本的 Ubuntu 20.04 LTS 安装包（或者默认最新版），然后双击解压后的 ubuntu2004.exe，等待安装完成。

安装完后设置 WSL2：

wsl --set-version Ubuntu-20.04 2
# 查看当前状态，确认没有报错
wsl --status

问题3：ubuntu2004.exe安装异常，WSL2 内核未安装

双击ubuntu2004.exe后  Installing, this may take a few minutes...
WslRegisterDistribution failed with error: 0x800701bc
Error: 0x800701bc WSL 2  https://aka.ms/wsl2kernel
Press any key to continue...

这个错误很明显——WSL2 内核还没装上。双击下载的 wsl_update_x64.msi 文件即可。

再设置默认 WSL 版本为 2：

wsl --set-default-version 2
wsl --status

然后再次双击 ubuntu2004.exe。

需要特别注意的是：如果手动安装 MSI 仍然报错"处理器类型不支持"，说明你的系统或 CPU 确实不支持 WSL2。这时只能降级到 WSL1：

# 设置默认使用 WSL1
wsl --set-default-version 1

重新双击 ubuntu2004.exe 安装即可。WSL1 同样可以编译安装 Hermes，只是性能稍差，但不影响使用。

问题4：安装完wsl_update_x64.msi后 再双击ubuntu2004.exe 还是异常，CPU 虚拟化未开启

Installing, this may take a few minutes...
WslRegisterDistribution failed with error: 0x80370102
Error: 0x80370102 

错误 0x80370102 通常表示 BIOS/UEFI 中 CPU 虚拟化未开启，或者 Windows 虚拟机平台功能未生效。

先确认系统版本：在 PowerShell 执行 winver，弹出的窗口查看版本号。2004（Build 19041）及以上才支持 WSL2。

接着检查 CPU 虚拟化：打开任务管理器 → 性能标签页 → 点击左侧 CPU → 右下角查看"虚拟化"状态，应为"已启用"。

最后确认 Windows 功能是否启用：在 PowerShell 重新执行：

# 启用虚拟机平台（WSL2 必需）
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 启用 Hyper-V（部分系统需要）
dism.exe /online /enable-feature /featurename:Microsoft-Hyper-V /all /norestart

执行完重启电脑，然后再双击 ubuntu2004.exe。

总之，还没到装 Hermes 那一步，光是 WSL 和 Ubuntu 系统就够折腾一阵子了。终于顺利进入 Ubuntu 终端，接下来才是真正的主角。

三、Hermes 安装问题

问题5： WSL 1 is not supported. Please upgrade to WSL 2

在 ubuntu 中运行 npm install -g hermes-web-ui 时，遇到了这个错误：

WSL 1 is not supported. Please upgrade to WSL 2 or above.

Could not determine Node.js install directory

之前因为 WSL2 装不上，就临时用了 WSL1 来试，结果验证了 Hermes 确实强制要求 WSL2。没办法，用尽前面招数把 WSL2 搞定。

安装完成 WSL2 Ubuntu 后，在终端中安装 hermes-web-ui：

# 安装 Node.js
sudo apt update
sudo apt install -y nodejs npm

# 安装 hermes-web-ui
sudo npm install -g hermes-web-ui

# 启动
hermes-web-ui start

默认版本是 node v10.19.0 和 npm 6.14.4。结果又遇到 Could not determine Node.js install directory 错误，改用以下方式解决：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g hermes-web-ui

启动后，在 Ubuntu 终端中用以下命令查看端口监听情况：

ss -tlnp | grep 8648
# 或者
netstat -tlnp | grep 8648

问题6：npm install -g hermes-web-ui运行异常，Node.js 版本过低

Rebuilding because directory /usr/local/lib/node_modules/hermes-web-ui/node_modules/node-pty/prebuilds/linux-x64 does not exist
gyp ERR! configure error
gyp ERR! stack Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/hermes-web-ui/node_modules/node-pty/build'
gyp ERR! System Linux 4.4.0-19041-Microsoft
gyp ERR! command "/usr/bin/node" "/usr/bin/node-gyp" "rebuild"
gyp ERR! cwd /usr/local/lib/node_modules/hermes-web-ui/node_modules/node-pty
gyp ERR! node -v v10.19.0
gyp ERR! node-gyp -v v6.1.0
gyp ERR! not ok
npm WARN notsup Unsupported engine for hermes-web-ui@0.5.32: wanted: {"node":">=23.0.0"} (current: {"node":"10.19.0","npm":"6.14.4"})
npm WARN notsup Not compatible with your version of node/npm: cliui@8.0.1
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! node-pty@1.1.0 install: `node scripts/prebuild.js || node-gyp rebuild`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the node-pty@1.1.0 install script.
npm ERR!    'Error: EACCES: permission denied, access '/usr/local/lib''

两个原因导致失败：Node.js 版本太老（Ubuntu 20.04 默认源里的 Node.js 是 v10.19.0，但 hermes-web-ui 要求 Node.js >= 23.0.0），以及权限问题（用 sudo npm install -g 会导致系统目录权限混乱）。

解决方案：用 nvm 安装新版 Node.js

nvm（Node Version Manager）可以安装任意版本的 Node.js，而且不需要 sudo。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

然后用 nvm 安装 Node.js 23：

nvm install 23
npm install -g hermes-web-ui

问题7：nvm安装异常 curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused

国内访问 GitHub 经常被拦。这种情况可以用 Gitee 国内镜像安装 nvm：

curl -o- https://gitee.com/mirrors/nvm/raw/v0.39.7/install.sh | bash

安装完后，重新打开一个 Ubuntu 终端（或者执行 source ~/.bashrc），然后：

# 配置 nvm 使用国内 Node.js 镜像（下载更快）
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node

# 安装 Node.js 23
nvm install 23
# 验证版本
node -v   # 应显示 v23.x.x
npm -v    # 应显示 10.x.x

问题8：nvm 命令找不到

Command 'nvm' not found

运行完安装脚本后，终端提示 nvm --version 报错：

Command 'nvm' not found, did you mean:
command 'lvm' from deb lvm2 (2.03.07-1ubuntu1)

原因很简单——终端会话没有加载 nvm 的环境变量。手动写入 .bashrc：

# 手动把 nvm 配置写入 .bashrc
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' >> ~/.bashrc
# 重新加载
source ~/.bashrc
# 验证
nvm --version

问题9：nvm install 23 返回Computing checksum with sha256sum

Checksums matched!
Your project npmrc file (/mnt/c/Users/Administrator/.npmrc)
has a `globalconfig` and/or a `prefix` setting, which are incompatible with nvm.
Run `nvm use --delete-prefix v23.11.1` to unset it.

这个错误是因为 Windows 上的 npm 配置干扰了 WSL2 里的 nvm。Windows 用户目录（C:\Users\Administrator）里有一个 .npmrc 文件，里面设置了 prefix 或 globalconfig，WSL2 挂载了 Windows 磁盘，npm 读取到了这个配置，与 nvm 冲突。

解决方法

在 Ubuntu 终端中执行提示的命令：

nvm use --delete-prefix v23.11.1

如果该命令返回 unexpected 错误：

/home/james/.nvm/versions/node/v23.11.1/bin/node: 1: Syntax error: ")" unexpected

这个错误说明 Node.js 23 的二进制文件与当前 WSL2 环境不兼容。原因很可能是 WSL2 的 Linux 内核版本较老，或者 nvm 下载的 Node.js 23 是 ARM64 架构而非 x64。

这种情况可以尝试安装 Node.js 20（后面排查发现不是 Node 版本问题，最终还是回到 23）。但安装 20 后可能又出现新的异常：

npm -v 输出npm error config prefix cannot be changed from project config: /mnt/c/Users/Administrator/.npmrc.
10.8.2

还是 Windows 的 .npmrc 在捣乱。直接处理掉：

# 备份并删除 Windows 用户的 .npmrc
mv /mnt/c/Users/Administrator/.npmrc /mnt/c/Users/Administrator/.npmrc.bak
# 重新加载 nvm
source ~/.bashrc
# 验证 npm 是否正常
npm -v

四、运行时问题

问题10：API 调用 502 错误

重新配置好模型后，输入对话内容时出现：Error: API Error 502: {"error":{"message":"Proxy error: fetch failed"}}

502 Proxy error: fetch failed 说明 hermes-web-ui 这个应用本身无法连到外部 API。但之前用 curl 直接测试是成功的——这通常是 WSL2 网络/袋里环境问题。

在 WSL 里运行 curl https://api.deepseek.com/v1/models -H "Authorization: Bearer sk-xxxx"，正常返回了模型列表。再运行 env | grep -i proxy，返回空。这说明 hermes-web-ui 内部的请求转发层出了问题，不是网络或 Key 的问题。

后面检查发现是 Hermes 网关没有启动。

检查网关是否正常运行

在 WSL2 Ubuntu 终端中执行：

# 查看 hermes-web-ui 进程
ps aux | grep hermes

# 查看端口监听
ss -tlnp | grep 8648
ss -tlnp | grep 3000   # 网关默认可能跑在 3000 或其他端口

正常应该看到至少两个进程：一个监听 8648（Web UI 前端），另一个监听另一个端口（网关后端）。

问题11：网关没有启动

hermes-web-ui 启动时应该自动启动网关。如果手动关闭了或配置分离了，可以尝试：

# 确保完整启动（包含网关）
hermes-web-ui start --gateway

问题12：OpenRouter 免费模型速率限制

使用 https://openrouter.ai/api/v1 时，第一次会话正常返回，第二次请求就报错：

API call failed (attempt 3/3) error_type=RateLimitError
summary=HTTP 429: Provider returned error

OpenRouter 的免费模型有速率限制——通常是 10-20 请求/分钟。第一次请求后，第二次就触发限流了。这是 OpenRouter 免费 tier 的正常行为，无法绕过。