Hermes Agent 在 Windows WSL2 中的安装与使用教程-拓冰网站定制

本文记录 Windows 11 + Ubuntu WSL2 + Clash Verge 环境下安装 Hermes Agent 的完整流程。

1. 环境说明

本教程适用于：

Windows 11
WSL2 Ubuntu
Clash Verge 或兼容的本地代理
需要访问 GitHub、PyPI、Node.js、Playwright 下载源的环境

Hermes Agent 的代码安装在 WSL Ubuntu 内，不建议在 Windows PowerShell 中直接执行 Linux 安装命令。

2. 先确认 WSL2

在 Windows PowerShell 中执行：

wsl --version wsl --status wsl -l -v

确认 Ubuntu 的VERSION为2。如果 Ubuntu 尚未安装，可以先执行：

wsl --install -d Ubuntu

安装完成后打开 Ubuntu，确认用户名和家目录。

3. 配置 WSL 网络

3.1 推荐的最终配置

本次实际验证中，WSL 镜像网络在当前环境下初始化失败，只剩回环网卡。因此最终使用 NAT 网络，由 Clash 虚拟网卡接管外网流量。

创建或更新 Windows 文件：

C:\Users\<Windows用户名>\.wslconfig

内容如下：

[wsl2] networkingMode=nat dnsTunneling=true autoProxy=false firewall=true

保存后，在管理员 PowerShell 执行：

wsl --shutdown

重新打开 Ubuntu，检查网络：

ip -brief address ip route cat /etc/resolv.conf

正常情况下应当看到eth0、默认路由和nameserver。

3.2 Clash Verge 设置

在 Clash Verge 的设置中打开：

虚拟网卡模式
系统代理
局域网连接

本教程使用 HTTP 代理端口7897。如果你的端口不同，后续命令中的7897要替换成实际端口。

验证 Windows 代理端口：

Get-NetTCPConnection -LocalPort 7897 -State Listen

3.3 WSL 访问 Clash 代理

在 Ubuntu 中获取 Windows 宿主机地址：

WIN_HOST=$(ip route | awk '/default/ {print $3}') echo "$WIN_HOST"

临时设置当前终端代理：

export HTTP_PROXY="http://${WIN_HOST}:7897" export HTTPS_PROXY="http://${WIN_HOST}:7897" export ALL_PROXY="http://${WIN_HOST}:7897"

测试代理出口：

curl -4 -x "http://${WIN_HOST}:7897" https://ipinfo.io

如果返回美国出口 IP 和地区信息，说明代理链路正常。

3.4 防火墙规则

如果 Ubuntu 访问${WIN_HOST}:7897超时，而 Windows 本机访问127.0.0.1:7897正常，在管理员 PowerShell 中创建仅限 WSL 子网的规则：

New-NetFirewallRule ` -DisplayName "Clash-Wsl-7897" ` -Direction Inbound ` -Action Allow ` -Protocol TCP ` -LocalPort 7897 ` -RemoteAddress 192.168.128.0/20 ` -Profile Any

确认规则：

Get-NetFirewallRule -DisplayName "Clash-Wsl-7897"

该规则只允许当前 WSL NAT 子网访问 Clash 的 7897 端口，不是向整个互联网开放代理。

4. 安装前网络检查

在 Ubuntu 中执行：

curl -4 -I --connect-timeout 10 \ https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh curl -4 -I --connect-timeout 10 https://github.com/NousResearch/hermes-agent curl -4 -I --connect-timeout 10 https://pypi.org/simple/

至少应当能够返回 HTTP 响应。若命令提示Could not resolve host，先修复 WSL DNS；若提示连接超时，检查 Clash 局域网连接和 Windows 防火墙规则。

5. 下载并检查官方安装脚本

在 Ubuntu 中执行：

curl -fsSLO https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh less install.sh bash -n install.sh

bash -n只检查脚本语法，不会执行安装。

6. 执行 Hermes 安装

确认脚本内容后执行：

export WIN_HOST=$(ip route | awk '/default/ {print $3}') export HTTP_PROXY="http://${WIN_HOST}:7897" export HTTPS_PROXY="http://${WIN_HOST}:7897" export ALL_PROXY="http://${WIN_HOST}:7897" bash install.sh

安装器通常会完成以下工作：

安装 Hermes 专用uv
安装或复用兼容版本的 Python
安装 Hermes Agent Git 仓库
创建 Python 虚拟环境
安装 Python 依赖
安装 Hermes 管理的 Node.js
安装 Playwright 浏览器工具
安装 Computer Use 驱动
创建配置文件和内置技能

安装器询问是否安装ripgrep、ffmpeg或编译工具时：

ripgrep：加快文件搜索，可选
ffmpeg：语音消息和音视频处理，可选
编译工具：某些 Python/Node 原生依赖需要，可按提示安装

如果没有 sudo 密码，可以先选择跳过可选系统包；核心 Hermes 安装仍可继续。

7. 网络异常时的依赖安装方案

7.1`astral.sh`超时

如果安装器提示无法下载https://astral.sh/uv/install.sh，先显式设置宿主机代理，再手动安装 uv：

WIN_HOST=$(ip route | awk '/default/ {print $3}') export HTTP_PROXY="http://${WIN_HOST}:7897" export HTTPS_PROXY="http://${WIN_HOST}:7897" export ALL_PROXY="http://${WIN_HOST}:7897" mkdir -p "$HOME/.hermes/bin" curl -4 -LsSf https://astral.sh/uv/install.sh -o /tmp/uv-install.sh UV_UNMANAGED_INSTALL="$HOME/.hermes/bin" sh /tmp/uv-install.sh "$HOME/.hermes/bin/uv" --version

7.2`files.pythonhosted.org`TLS 握手失败

某些代理节点可以访问pypi.org，但访问files.pythonhosted.org时 TLS 握手失败。此时使用阿里云 PyPI 镜像：

export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/ export UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple/ export UV_HTTP_TIMEOUT=120 export UV_EXCLUDE_NEWER=false

先验证镜像：

curl -4 -I \ -x "http://${WIN_HOST}:7897" \ https://mirrors.aliyun.com/pypi/simple/anyio/

7.3 项目`exclude-newer`导致镜像包被过滤

Hermes 项目可能对依赖设置最近发布期限，镜像缺少上传时间时会出现：

No solution found when resolving dependencies

对本次安装可临时设置：

export UV_EXCLUDE_NEWER=false

不要为了绕过问题直接修改 Hermes 仓库中的pyproject.toml或uv.lock。

如果锁文件同步仍因镜像元数据失败，可以导出带哈希的锁定依赖：

cd "$HOME/.hermes/hermes-agent" "$HOME/.hermes/bin/uv" export \ --frozen \ --extra all \ --no-dev \ --no-emit-project \ --format requirements.txt \ --output-file /tmp/hermes-requirements.txt

再按哈希安装：

"$HOME/.hermes/bin/uv" pip install \ --python "$HOME/.hermes/hermes-agent/venv/bin/python" \ --no-config \ --require-hashes \ --index-url https://mirrors.aliyun.com/pypi/simple/ \ -r /tmp/hermes-requirements.txt

这样仍然使用项目锁文件导出的固定版本和 SHA256 哈希。

8. Playwright 系统依赖

如果浏览器启动时报错，例如：

libnspr4.so: cannot open shared object file

用 root 身份执行官方依赖安装命令：

cd "$HOME/.hermes/hermes-agent" sudo npx playwright install-deps chromium

如果当前用户没有 sudo 权限，可以从 Windows PowerShell 调用 WSL root：

wsl -d Ubuntu -u root -- bash -lc ` 'cd /home/<用户名>/.hermes/hermes-agent && ` /home/<用户名>/.hermes/node/bin/npx playwright install-deps chromium'

验证 Chromium：

cd "$HOME/.hermes/hermes-agent" export PATH="$HOME/.hermes/node/bin:$PATH" export PLAYWRIGHT_BROWSERS_PATH="$HOME/.cache/ms-playwright" npx playwright screenshot about:blank /tmp/hermes-browser-test.png test -s /tmp/hermes-browser-test.png && echo browser_ok

9. 安装完成后的检查

重新加载 Shell：

source ~/.bashrc

检查命令和版本：

command -v hermes hermes --version hermes --help

正常情况下会看到：

Hermes Agent v0.21.x Python: 3.11.x

检查配置文件：

ls -l ~/.hermes/config.yaml ~/.hermes/.env find ~/.hermes/skills -mindepth 1 -maxdepth 1 -type d | wc -l

10. 首次配置和使用

启动配置向导：

hermes setup

常见选项：

Quick Setup：通过 Nous Portal OAuth 配置，不需要手填模型 API Key
Full setup：逐项配置模型供应商、工具和选项
Blank Slate：关闭大部分可选能力，仅保留最小功能

OAuth 登录需要用户自己在浏览器中完成，不要把账号、密码或 API Key 粘贴到聊天中。

配置完成后启动：

hermes

常用命令：

hermes setup hermes config hermes status hermes update hermes gateway install

11. 每次新开 Ubuntu 的代理

如果只需要当前终端代理：

WIN_HOST=$(ip route | awk '/default/ {print $3}') export HTTP_PROXY="http://${WIN_HOST}:7897" export HTTPS_PROXY="http://${WIN_HOST}:7897" export ALL_PROXY="http://${WIN_HOST}:7897"

如果经常在 WSL 中安装依赖，可以将以下内容追加到~/.bashrc，但要确认 Clash 端口固定且只在可信网络中使用：

export WIN_HOST=$(ip route | awk '/default/ {print $3}') export HTTP_PROXY="http://${WIN_HOST}:7897" export HTTPS_PROXY="http://${WIN_HOST}:7897" export ALL_PROXY="http://${WIN_HOST}:7897"

修改后执行：

source ~/.bashrc

12. 常见故障

12.1 出现 localhost 代理警告

检测到 localhost 代理配置，但 WSL NAT 模式下的 WSL 不支持 localhost 代理

这表示 Windows 系统代理是127.0.0.1:7897，但 NAT 模式下 Ubuntu 不能直接访问 Windows localhost。使用宿主机地址${WIN_HOST}:7897，并开启 Clash 局域网连接。

12.2 Ubuntu 只有`lo`，没有`eth0`

通常是镜像网络初始化失败。将.wslconfig改回：

[wsl2] networkingMode=nat dnsTunneling=true autoProxy=false firewall=true

然后执行：

wsl --shutdown

12.3`Could not resolve host`

先检查：

cat /etc/resolv.conf ip route

如果没有默认路由或/etc/resolv.conf不存在，先修复 WSL 网络；不要一开始就手工写死 DNS。

12.4 安装器重复失败

不要同时运行多个安装脚本。确认当前安装目录状态：

ls -la ~/.hermes hermes --version

安装器支持重复执行，已完成的 uv、Node、仓库和虚拟环境通常会被复用。

12.5 Browser Use CLI 安装失败

这不等于 Hermes 浏览器工具全部不可用。先验证 Playwright：

cd ~/.hermes/hermes-agent npx playwright screenshot about:blank /tmp/test.png

必要时再手动安装：

~/.hermes/bin/uv tool install browser-use

13. 安全与清理

本教程创建的 Windows 防火墙规则可以删除：

Remove-NetFirewallRule -DisplayName "Clash-Wsl-7897"

删除前确认 Ubuntu 不再需要通过宿主机的 7897 端口访问代理。

不要将以下内容提交到 Git 或发送给他人：

~/.hermes/.env
模型 API Key
OAuth 凭据
代理认证信息

14. 本次验证结果

本次环境最终验证通过：

Ubuntu 出口 IP：美国洛杉矶
GitHub：HTTP 200
Raw GitHub：HTTP 200
PyPI 镜像：可访问
Hermes CLI：v0.21.4
Python：3.11.16
Node.js：v26.9.0
Playwright Chromium：可启动
Computer Use 驱动：安装成功

资讯详情

Hermes Agent 在 Windows WSL2 中的安装与使用教程