当前位置： 首页  >   攻略资讯  >   手游攻略  >   Hermes Agent安装中的踩坑记录及解决方案

Hermes Agent安装中的踩坑记录及解决方案

时间：2026-07-08 08:41:42 来源：互联网

网上虽有很多关于 Hermes 的安装教程，但大多仅展示成功截图，未能揭示实际安装过程中因环境复杂而出现的各种问题。本文基于真实踩坑经历，详细记录了从 WSL2 环境准备到 Hermes 部署的每一步关键问题与解决方案。

一、环境准备：WSL2 安装

Hermes 原生不支持 Windows，因此在 win10 上安装时，推荐优先部署 Ubuntu 虚拟机，再于其中安装 Hermes。为此，首先需要开启 WSL2（Windows Subsystem for Linux 2），它并非安装第二个操作系统，而是为 Windows 添加一个 Linux 插件层。

系统要求

系统需 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
# 查看当前状态，确认没有报错,没有报错，说明 WSL2 修复成功
wsl --status

若系统提示需更新 WSL2 Linux 内核，请下载并安装 wsl_update_x64.msi。安装更新包后，再次执行上述命令以完成配置。

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

以管理员身份打开 PowerShell，输入命令 wsl --install。

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

img_6a4d9cc5e56ff30.webp

更新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
# 查看当前状态，确认没有报错,没有报错，说明 WSL2 修复成功
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...

双击下载的 wsl_update_x64.msi 文件，然后设置默认 WSL 版本为 2：

wsl --set-default-version 2
# 查看当前状态，确认没有报错,没有报错，说明 WSL2 修复成功
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 虚拟机平台功能未生效。请按以下步骤排查：

  1. 在 PowerShell 中执行 winver，在弹出的窗口中查看版本号是否为 2004（Build 19041）及以上，此版本支持 WSL2。

img_6a4d9cc6558a831.webp

  1. 检查 CPU 虚拟化是否开启：打开任务管理器，点击“性能”标签页，点击左侧 CPU，在右下角查看“虚拟化”状态是否为“已启用”。
  2. 确认 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。

三、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，结果出现如上异常。这表明必须使用 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 和 npm6.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

启动 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''
……

两个原因导致失败：

  1. Node.js 版本太老：Ubuntu 20.04 默认源里的 Node.js 是 v10.19.0，但 hermes-web-ui 要求 Node.js >= 23.0.0
  2. 权限问题：用 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
再重装hermes-web-ui
npm install -g hermes-web-ui

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

国内访问 GitHub 被拦截时，可改用 Gitee 国内镜像安装 nvm：

# 用 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

运行curl -o- https://gitee.com/mirrors/nvm/raw/v0.39.7/install.sh | bash后  
nvm --version
Command 'nvm' not found, did you mean:
command 'lvm' from deb lvm2 (2.03.07-1ubuntu1)

这是因为当前终端会话未加载 nvm 的环境变量。请执行：

# 手动把 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:UsersAdministrator）下的 .npmrc 文件设置了 prefix 或 globalconfig，WSL2 挂载 Windows 磁盘时读取了该配置，导致与 nvm 冲突。

解决方法

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

nvm use --delete-prefix v23.11.1

nvm use --delete-prefix v23.11.1命令返回unexpected

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

此错误表明 Node.js 23 的二进制文件与当前 WSL2 环境不兼容，可能原因包括：WSL2 的 Linux 内核版本较老（之前显示 5.10.16），或 nvm 下载的 Node.js 23 是 ARM64 架构而非 x64。此处曾建议安装 node20（后经排查非版本问题，仍可用 23 版本），但安装后又出现异常：

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

node.js 20 安装成功，但 Windows 的 .npmrc 文件仍在干扰 npm。直接处理该干扰：

# 备份并删除 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"，若正常返回 JSON 数据，则说明网络和 Key 无问题。运行 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 异常：

用 https://openrouter.ai/api/v1 第一次会话能正常返回信息，第二次请求时就异常 
API call failed (attempt 3/3) error_type=RateLimitError thread=asyncio_0:140437168981760 provider=custom base_url=https://openrouter.ai/api/v1 model=deepseek/deepseek-v4-flash:free summary=HTTP 429: Provider returned error
2026-05-21 17:12:59,243 ERROR [mpf9qgqnev5sm9] root: API call failed after 3 retries. HTTP 429: Provider returned error | provider=custom model=deepseek/deepseek-v4-flash:fre

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

上一篇：麻花豆MV在线看-麻花豆TV免费观看 下一篇：跨平台多模态智能体基准测试来了:但全班第一只考了35.26分