Hermes Agent Web UI在Windows 10/11WSL2下的完整安装指南本指南适用于希望在一台Windows电脑上通过WSL2部署Hermes Agent命令行界面和hermes-web-uiWeb管理界面的用户。所有步骤均经过验证可稳定运行。一、准备工作1.1系统要求Windows 10 版本 2004 及以上内部版本 19041 及以上或 Windows 11至少 8GB 内存推荐 16GB网络能够访问 GitHub若速度慢请参考下文“加速技巧”1.2开启WSL2和虚拟机平台以管理员身份打开PowerShell执行dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart然后重启电脑。重启后继续以管理员身份运行PowerShell设置WSL2为默认版本wsl --set-default-version 2二、安装Ubuntu 22.04解决下载慢问题2.1常规安装如果网络良好直接执行wsl --install -d Ubuntu-22.042.2如果下载缓慢或超时方法一使用--web-download参数从 GitHub 直接下载避开微软商店wsl --install -d Ubuntu-22.04 --web-download方法二手动下载并导入最稳定从WSL 发行版 GitHub 仓库或Ubuntu WSL 镜像下载ubuntu-22.04-server-cloudimg-amd64-wsl.rootfs.tar.gz。在 PowerShell 中执行mkdir D:\WSL\Ubuntu-22.04 # 安装到 D 盘可自定义 wsl --import Ubuntu-22.04 D:\WSL\Ubuntu-22.04 D:\下载路径\ubuntu-22.04-server-cloudimg-amd64-wsl.rootfs.tar.gz --version 2 #设置默认用户可选 powershell wsl -d Ubuntu-22.04#进入后创建用户useradd -m -G sudo -s /bin/bash yourname然后passwd yourname再编辑/etc/wsl.conf设置默认用户方法三配置国内镜像源若wsl --install卡在“正在下载”可尝试修改 DNS 或使用代理。在 Windows 的C:\Windows\System32\drivers\etc\hosts中添加185.199.108.133 raw.githubusercontent.com 185.199.109.133 raw.githubusercontent.com 185.199.110.133 raw.githubusercontent.com 185.199.111.133 raw.githubusercontent.com安装完成后从开始菜单启动 Ubuntu按提示创建普通用户请勿使用root。三、安装Hermes Agent自动处理所有依赖3.1进入Ubuntu终端更新软件源并安装Gitsudo apt update sudo apt install -y git curl3.2执行官方安装脚本自动安装Python 3.11、Node.js v22等如果你的网络访问GitHub较慢请使用国内镜像加速。方式A推荐使用加速镜像curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash方式B使用GitCode镜像克隆git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git ~/.hermes/hermes-agent cd ~/.hermes/hermes-agent bash scripts/install.sh --local方式C如果上述均失败手动配置hosts在/etc/hosts中添加185.199.108.133 raw.githubusercontent.com然后重试方式A。安装脚本会自动完成安装 Python 3.11若系统中没有安装 Node.js v22 LTS~/.hermes/node/bin安装ripgrep、ffmpeg等工具创建虚拟环境并安装 Python 依赖注意此过程中无需你手动安装nvm或Node.js脚本已妥善处理。3.3刷新环境变量并验证source ~/.bashrc hermes doctor此时若看到API key not configured或OpenRouter API (not configured)属于正常现象下一步会配置。️四、配置Hermes Agent选择模型提供商运行配置向导hermes setup按照提示完成选择模型提供商可选OpenRouter推荐聚合多家模型、OpenAI、Anthropic等或使用自定义端点如你已有的gpt-oss-20b。输入API Key若使用付费服务或跳过若使用本地模型。选择默认模型。如果你已有自定义端点可直接在~/.hermes/.env中设置CUSTOM_API_KEYyour_key CUSTOM_BASE_URLhttp://your_endpoint/v1之后通过hermes model选择自定义模型。配置完成后再次运行hermes doctor确认API key or custom endpoint configured为✓。五、安装hermes-web-uiWeb管理面板Hermes安装脚本已经为你安装了Node.js因此可以直接使用npm。5.1全局安装hermes-web-uinpm install -g hermes-web-ui如果提示command not found请将npm全局bin目录加入PATHecho export PATH$(npm prefix -g)/bin:$PATH ~/.bashrc source ~/.bashrc5.2启动Web UIhermes-web-ui start成功后在Windows浏览器中访问http://localhost:8648即可。注意hermes-web-ui需要Hermes网关服务在后台运行。如果页面提示连接错误请另开一个终端窗口执行hermes gateway run保持前台运行然后刷新Web UI。六、验证与常用命令启动命令行交互hermes启动Web UIhermes-web-ui start运行诊断hermes doctor更新Hermeshermes update若后续需要️七、可选优化与故障排除7.1增加WSL内存限制避免Windows卡顿在Windows用户目录C:\Users\你的用户名\下创建.wslconfig内容ini [wsl2] memory4GB processors2然后重启WSLwsl --shutdown7.2配置国内镜像加速npm下载npm config set registry https://registry.npmmirror.com7.3若hermes-web-ui启动后无法连接确认hermes gateway run在另一个终端中运行。检查防火墙是否允许 8648 端口。7.4若hermes doctor提示agent-browser not installed这是可选的浏览器自动化工具如需安装npm install -g agent-browser agent-browser install