Hermes Agent安装踩坑复盘

网上很多手把手安装的教程已经很详细了大多数都是一把过但都没有把其中每一步安装的问题暴露出来都是贴出成功的截图真实的是由于环境的复杂性从第一步就碰到了问题其中大部分都是贴问题给deepseek或kimi来一步一个坑的来解决反复折腾现在复盘记录下大部分的问题。一、环境准备WSL2 安装win10安装HermesHermes 原生不支持 Windows推荐优先安装Ubuntu虚拟机再在虚拟机里面安装hermes。Windows 要先开 WSL2Windows 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 默认版本为 2wsl --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.04install等待部署完成重新启动电脑。问题2win10安装Ubuntu异常错误代码: 0x80072ee7正在下载: Ubuntu 20.04 LTS 安装过程中出现错误。分发名称: Ubuntu 20.04 LTS 错误代码: 0x80072ee7提前下载指定版本 Ubuntu 20.04 LTS 或 Ubuntu默认最新版安装包。双击解压后的ubuntu2004.exe等待安装完成安装完后设置 WSL2wsl --set-version Ubuntu-20.04 2 # 查看当前状态确认没有报错,没有报错说明 WSL2 修复成功 wsl --status问题3ubuntu2004.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 版本为 2wsl --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 执行以下命令弹出的窗口看版本号2004Build 19041是支持wsl2的。winver2.检查 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 2ubuntu中运行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问题6npm 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-ui0.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: cliui8.0.1 npm ERR! code ELIFECYCLE npm ERR! errno 1 npm ERR! node-pty1.1.0 install: node scripts/prebuild.js || node-gyp rebuild npm ERR! Exit status 1 npm ERR! npm ERR! Failed at the node-pty1.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.jsnvmNode Version Manager可以安装任意版本的 Node.js且不需要 sudo。curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash再用nvm安装Node.js 23nvm install 23 再重装hermes-web-ui npm install -g hermes-web-ui问题7nvm安装异常 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_MIRRORhttps://npmmirror.com/mirrors/node # 安装 Node.js 23 nvm install 23 # 验证版本 node -v # 应显示 v23.x.x npm -v # 应显示 10.x.x问题8nvm 命令找不到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问题9nvm install 23 返回Computing checksum with sha256sumChecksums 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或globalconfigWSL2 挂载了 Windows 磁盘npm 读取到了这个配置与 nvm 冲突。解决方法在 Ubuntu 终端中执行提示的命令nvm use --delete-prefix v23.11.1nvm 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.2node.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四、运行时问题问题10API 调用 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 或其他端口正常应该看到至少两个进程一个监听8648Web UI 前端一个监听另一个端口网关后端问题11网关没有启动hermes-web-ui 启动时应该自动启动网关。如果手动关闭了或配置分离了尝试# 确保完整启动包含网关 hermes-web-ui start --gateway问题12OpenRouter 免费模型速率限制用 OpenRouter 第一次会话能正常返回信息第二次请求时就异常 API call failed用 https://openrouter.ai/api/v1 第一次会话能正常返回信息第二次请求时就异常 API call failed (attempt 3/3) error_typeRateLimitError threadasyncio_0:140437168981760 providercustom base_urlhttps://openrouter.ai/api/v1 modeldeepseek/deepseek-v4-flash:free summaryHTTP 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 | providercustom modeldeepseek/deepseek-v4-flash:freOpenRouter 的免费模型有速率限制通常是 10-20 请求/分钟你第一次请求后第二次触发限流了。这是 OpenRouter 免费 tier 的正常行为无法绕过