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

伞伞悦读2026-10-04 11:06

本文记录 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 驱动：安装成功

相关推荐
YOLO数据集集合1 小时前
河道环境智能检测系统（YOLO + DeepSeek） | 河道巡检 YOLO DeepSeek 大语言模型 智慧水利 9144期
人工智能·yolo·目标检测·语言模型·河道污染·城市治理
硅谷秋水13 小时前
EmbodiedMemory-Bench：面向长时程具身任务的具身记忆基准测试
机器学习·语言模型·机器人
Dawson Zhu19 小时前
智能体记忆系统：原理解析与工程实践
人工智能·语言模型·架构·aigc·agi
YOLO数据集集合1 天前
大模型融合YOLO铁路要素缺陷分析系统 | 铁路缺陷检测 YOLO DeepSeek 大语言模型 智能巡检 9141期
人工智能·yolo·目标检测·语言模型·铁路缺陷·轨道缺陷
大模型任我行1 天前
阿里：通义千问3.8全能版发布
人工智能·语言模型·自然语言处理·论文笔记
Dawson Zhu1 天前
大语言模型对齐与微调：原理解析与工程实践
人工智能·语言模型·架构·aigc·agi
东方芷兰1 天前
Agent 技术摘要 05 —— BP、SaaS、B2B、C2B、B2C
java·笔记·python·语言模型·自然语言处理
Dawson Zhu1 天前
Agent上下文压缩的“状态保真“取舍框架解读
人工智能·语言模型·架构·aigc·agi
Dawson Zhu1 天前
Cookbook Agent：拓扑Codebook方法与多Agent通信效率优化
人工智能·语言模型·架构·aigc·agi
热门推荐
01如何新建文件夹？ 电脑新建文件夹的4种方法02国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）03历年考研数学一、数学二、数学三真题试卷及答案PDF04Telegram APK 下载安装完整指南 — 2026年最新05GitHub 镜像站点06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接072026 爱知・名古屋亚运会怎么看？直播平台+赛程安排分享08微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新09Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）10给AI一张“业务概念地图“：本体如何从哲学走向企业智能