本文记录 Windows 11 Ubuntu WSL2 Clash Verge 环境下安装 Hermes Agent 的完整流程。1. 环境说明本教程适用于Windows 11WSL2 UbuntuClash 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] networkingModenat dnsTunnelingtrue autoProxyfalse firewalltrue保存后在管理员 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 Listen3.3 WSL 访问 Clash 代理在 Ubuntu 中获取 Windows 宿主机地址WIN_HOST$(ip route | awk /default/ {print $3}) echo $WIN_HOST临时设置当前终端代理export HTTP_PROXYhttp://${WIN_HOST}:7897 export HTTPS_PROXYhttp://${WIN_HOST}:7897 export ALL_PROXYhttp://${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.shbash -n只检查脚本语法不会执行安装。6. 执行 Hermes 安装确认脚本内容后执行export WIN_HOST$(ip route | awk /default/ {print $3}) export HTTP_PROXYhttp://${WIN_HOST}:7897 export HTTPS_PROXYhttp://${WIN_HOST}:7897 export ALL_PROXYhttp://${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.1astral.sh超时如果安装器提示无法下载https://astral.sh/uv/install.sh先显式设置宿主机代理再手动安装 uvWIN_HOST$(ip route | awk /default/ {print $3}) export HTTP_PROXYhttp://${WIN_HOST}:7897 export HTTPS_PROXYhttp://${WIN_HOST}:7897 export ALL_PROXYhttp://${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 --version7.2files.pythonhosted.orgTLS 握手失败某些代理节点可以访问pypi.org但访问files.pythonhosted.org时 TLS 握手失败。此时使用阿里云 PyPI 镜像export UV_INDEX_URLhttps://mirrors.aliyun.com/pypi/simple/ export UV_DEFAULT_INDEXhttps://mirrors.aliyun.com/pypi/simple/ export UV_HTTP_TIMEOUT120 export UV_EXCLUDE_NEWERfalse先验证镜像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_NEWERfalse不要为了绕过问题直接修改 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 rootwsl -d Ubuntu -u root -- bash -lc cd /home/用户名/.hermes/hermes-agent /home/用户名/.hermes/node/bin/npx playwright install-deps chromium验证 Chromiumcd $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_ok9. 安装完成后的检查重新加载 Shellsource ~/.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 -l10. 首次配置和使用启动配置向导hermes setup常见选项Quick Setup通过 Nous Portal OAuth 配置不需要手填模型 API KeyFull setup逐项配置模型供应商、工具和选项Blank Slate关闭大部分可选能力仅保留最小功能OAuth 登录需要用户自己在浏览器中完成不要把账号、密码或 API Key 粘贴到聊天中。配置完成后启动hermes常用命令hermes setup hermes config hermes status hermes update hermes gateway install11. 每次新开 Ubuntu 的代理如果只需要当前终端代理WIN_HOST$(ip route | awk /default/ {print $3}) export HTTP_PROXYhttp://${WIN_HOST}:7897 export HTTPS_PROXYhttp://${WIN_HOST}:7897 export ALL_PROXYhttp://${WIN_HOST}:7897如果经常在 WSL 中安装依赖可以将以下内容追加到~/.bashrc但要确认 Clash 端口固定且只在可信网络中使用export WIN_HOST$(ip route | awk /default/ {print $3}) export HTTP_PROXYhttp://${WIN_HOST}:7897 export HTTPS_PROXYhttp://${WIN_HOST}:7897 export ALL_PROXYhttp://${WIN_HOST}:7897修改后执行source ~/.bashrc12. 常见故障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] networkingModenat dnsTunnelingtrue autoProxyfalse firewalltrue然后执行wsl --shutdown12.3Could 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 浏览器工具全部不可用。先验证 Playwrightcd ~/.hermes/hermes-agent npx playwright screenshot about:blank /tmp/test.png必要时再手动安装~/.hermes/bin/uv tool install browser-use13. 安全与清理本教程创建的 Windows 防火墙规则可以删除Remove-NetFirewallRule -DisplayName Clash-Wsl-7897删除前确认 Ubuntu 不再需要通过宿主机的 7897 端口访问代理。不要将以下内容提交到 Git 或发送给他人~/.hermes/.env模型 API KeyOAuth 凭据代理认证信息14. 本次验证结果本次环境最终验证通过Ubuntu 出口 IP美国洛杉矶GitHubHTTP 200Raw GitHubHTTP 200PyPI 镜像可访问Hermes CLIv0.21.4Python3.11.16Node.jsv26.9.0Playwright Chromium可启动Computer Use 驱动安装成功