Hermes Agent中安装踩坑记录及解决方案
我要评论网上很多手把手安装的教程已经很详细了，大多数都是一把过，但都没有把其中每一步安装的问题暴露出来，都是贴出成功的截图，真实的是由于环境的复杂性从第一步就碰到了问题，其中大部分都是贴问题给deepseek或kimi来一步一个坑的来解决，反复折腾，现在复盘记录下大部分的问题。
一、环境准备：WSL2 安装
win10安装Hermes，Hermes 原生不支持 Windows，推荐优先安装Ubuntu虚拟机，再在虚拟机里面安装hermes。
Windows 要先开 WSL2（Windows Subsystem for Linux 2），在 Windows 里开一个 Linux 夹层。 你不是装第二个操作系统，你是给 Windows 加一个插件。
系统要求
Windows11任意版本 / 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
更新wsl异常
wsl --update 正在检查更新... 正在下载更新... 正在安装更新... 这个处理器类型不支持该安装程序包。请与产品供应商联系。
说明当前 Windows 系统架构（32位/64位/ARM）与 WSL2 更新包不匹配，或者 CPU 不支持虚拟化。
下载并安装 wsl_update_x64.msi，双击安装，完成后重启电脑
再执行
wsl --set-default-version 2 wsl --install -d Ubuntu-20.04
install等待部署完成， 重新启动电脑。
问题2：win10安装Ubuntu异常错误代码: 0x80072ee7
正在下载: Ubuntu 20.04 LTS 安装过程中出现错误。分发名称: 'Ubuntu 20.04 LTS' 错误代码: 0x80072ee7
提前下载指定版本 Ubuntu 20.04 LTS 或 Ubuntu（默认最新版）安装包。
双击解压后的 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，后面有其它组件版本不支持）：
# 设置默认使用 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 执行以下命令，弹出的窗口看版本号2004（Build 19041）是支持wsl2的。
winver
2.检查 CPU 虚拟化是否开启
打开任务管理器=>点击 性能 标签页=>点击左侧 CPU=>右下角看 "虚拟化" 状态：已启用
3.确认 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\''
……
两个原因导致失败：
- 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 再重装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:\Users\Administrator）里有一个 .npmrc 文件，里面设置了 prefix 或 globalconfig，WSL2 挂载了 Windows 磁盘，npm 读取到了这个配置，与 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(后面排查不是node版本问题，还是用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 干扰
# 备份并删除 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“
正常返回{"object":"list","data":[{"id":"deepseek-v4-flash","object":"model","owned_by":"deepseek"},{"id":"deepseek-v4-pro","object":"model","owned_by":"deepseek"}]}；
运行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 的正常行为，无法绕过
到此这篇关于Hermes Agent中安装踩坑记录及解决方案的文章就介绍到这了,更多相关Hermes Agent安装内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！
相关文章
Hermes Agent 桌面版安装部署完全指南：一步步安装自进化Agent智能体
Hermes Agent 是由 Nous Research 开发的开源自主 AI 智能体（MIT 协议），这篇文章给大家介绍Hermes Agent 桌面版安装部署完全指南：一步步安装自进化Agent智能体，感兴趣2026-07-02
最近在开源 Agent 圈里，Hermes Agent 的名字反复出现在各种讨论中,有人戏称它为爱马仕 Agent，这篇文章将从零开始部署 Hermes Agent 并接入飞书的完整过程做一个系统梳理2026-06-14
从0到1的Hermes Agent的保姆级教程详细学习与使用指南
本文将手把手带你从零开始，全面了解 Hermes Agent 的核心特性、安装部署方法、配置技巧以及进阶使用指南,无论你是技术小白还是资深开发者，都能通过这篇保姆级教程，打造2026-05-30
Hermes Agent安装、运行、使用常见错误总结与解决方案
本文提供了HermesAgent在Windows、WSL2、macOS、Linux及Termux等环境下的使用指南,包括常见错误排查、诊断命令、安装阶段常见错误、运行阶段常见错误等，希望可以帮助用户2026-05-19
Hermes Agent 安装部署攻略60秒入门这个可成长的AI助手
HermesAgent是一个自主运行的的A自主学习的AI代理,支持多多平台,具有自主成长、跨会话会议和记忆的特点,文章介绍安装和配置过程,,及使用、技能管理和定时任务的简要使用，2026-05-19- Hermes Agent 是 NousResearch 开源的个人 AI 助手，支持跨平台安装（Windows/macOS/Linux/WSL2/Android/NixOS）,本文提供从零安装指南，涵盖环境准备、依赖处理、模型配2026-05-18
macOS系统下安装与配置Hermes Agent的完整指南(收藏这一篇就够了)
Hermes Agent 支持 macOS，但安装过程有几个点需要注意,本文是 macOS 专属安装指南，覆盖从零配置到运行的全流程，以 MiniMax 为例演示 AI 提供商配置,有需要的小伙伴可以2026-05-11
本文详细介绍了Hermes Agent的本地快速部署流程，涵盖环境要求（Linux/macOS/WSL2），两种安装方式，API密钥配置等内容，希望可以帮助读者轻松完成HermesAgent的安装与配2026-05-08
最新评论