网上很多手把手安装的教程已经很详细了，大多数都是一把过，但都没有把其中每一步安装的问题暴露出来，都是贴出成功的截图，真实的是由于环境的复杂性从第一步就碰到了问题，其中大部分都是贴问题给deepseek或kimi来一步一个坑的来解决，反复折腾，现在复盘记录下大部分的问题。

win10安装Hermes，Hermes 原生不支持 Windows，推荐优先安装Ubuntu虚拟机，再在虚拟机里面安装hermes。

Windows 要先开 WSL2（Windows Subsystem for Linux 2），在 Windows 里开一个 Linux 夹层。 你不是装第二个操作系统，你是给 Windows 加一个插件。

Windows11任意版本 / Windows 10 要 ≥ 2004。

管理员身份打开 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 --set-default-version 2
# 查看当前状态，确认没有报错,没有报错，说明 WSL2 修复成功
wsl --status


提示需要更新 WSL2 Linux 内核，下载并安装 wsl_update_x64.msi

安装完更新包后，再次执行上面的命令

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

问题1：提示无效的install，需要升级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 或 Ubuntu（默认最新版）安装包。

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...


手动安装 MSI 也报错"处理器类型不支持"说明你的系统或 CPU 确实不支持 WSL2，需要降级到 WSL1（不要使用WSL1，后面有其它组件版本不支持）：

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


WSL1 同样可以编译安装 Hermes，只是性能稍差，不影响使用。

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

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


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

1.PowerShell 执行以下命令，弹出的窗口看版本号2004（Build 19041）是支持wsl2的。

打开任务管理器=>点击 性能 标签页=>点击左侧 CPU=>右下角看 "虚拟化" 状态：已启用

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

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


执行完重启电脑，然后再双击 

总之还没到安装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来试，结果报以上异常，看来必须用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


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\''
……


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

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

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


nvm install 23
再重装hermes-web-ui
npm install -g hermes-web-ui


问题7：nvm安装异常 curl: (7) Failed to connect to

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

# 用 Gitee 镜像下载 nvm 安装脚本
curl -o- https://gitee.com/mirrors/nvm/raw/v0.39.7/install.sh | bash


安装完后，重新打开一个 Ubuntu 终端（或执行 

# 配置 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


运行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。

，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
/home/james/.nvm/versions/node/v23.11.1/bin/node: 1: Syntax error: ")" unexpected


这个错误说明 Node.js 23 的二进制文件与你的 WSL2 环境不兼容。原因很可能是：

Hermes Agent安装踩坑复盘

编程语言

开发工具

后端

WSL2安装Hermes常见问题解决方案：Windows需开启WSL2和虚拟化功能，安装Ubuntu20.04时注意CPU架构匹配。Node.js版本需≥23.0.0，推荐使用nvm管理版本。安装过程可能遇到网络、权限、配置冲突等问题，需检查网关启动状态和API限流设置。详细步骤解决WSL2环境搭建、Node版本管理及Hermes运行问题。

虚拟化

虚拟机

Windows

GitHub

Ubuntu

Linux

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

WSL2安装Hermes常见问题解决方案：Windows需开启WSL2和虚拟化功能，安装Ubuntu20.04时注意CPU架构匹配。Node.js版本需≥23.0.0，推荐使用nvm管理版本。安装过程可能遇到网络、权限、配置冲突等问题，需检查网关启动状态和API限流设置。详细步骤解决WSL2环境搭建、Node版本管理及...

Hermes Agent安装踩坑复盘

Hermes Agent安装踩坑复盘

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐