从零在 Windows + WSL2 上安装 Hermes Agent:官方源、MTU 黑洞与代理的那些坑

最近在 Windows 10 + WSL2(Ubuntu) 上从 NousResearch 官方源完整安装了一遍 Hermes Agent,并接入了小米 MiMo Token Plan 作为推理后端。整个过程踩了几个非常典型的坑:跨境下载传一半就断、WSL 死活用不上 Windows 代理、配置怎么都固化不了。本文把诊断思路和最终方案完整记录下来,照着做就能一次装好。

先说结论:三个关键认知

WSL2 不会自动继承 Windows 的代理。它是独立虚拟机,有自己的网络栈,系统代理和环境变量互不相通,必须手动把流量指到宿主机 IP。
“下载传一半就断”的最高频根因是 WSL2 MTU 黑洞:路径 MTU 往往只有 1480,而 WSL 网卡默认 1500,加上 WSL2 的 NAT 常常丢弃 PMTUD 的 ICMP 回包,满尺寸数据包会被静默丢弃,表现就是 TLS 握手成功、传输中途 EOF。
WSL 配置固化的前提是新版本 WSL。/etc/wsl.conf 的 [boot] 段需要 WSL ≥ 0.67.6,老版内置 WSL 会静默忽略你的所有配置。

第一步:确认并升级 WSL 版本

在 PowerShell 里执行 wsl --version。如果报 “命令行选项无效: –version”,说明你和我一样用的是老版内置 WSL——此时 [boot]、systemd、udev 这些特性全部不可用。升级:

wsl --update
# Microsoft Store 下载卡住(常见于国内网络)时,Ctrl+C 后改走 GitHub:
wsl --update --web-download
# 还不行就手动下载 msixbundle 后安装:
Add-AppxPackage .\wsl.x.x.x.x64.msixbundle

升级后 wsl --shutdown 重启,验证:

systemctl is-active systemd-udevd   # 应输出 active

第二步:诊断 MTU 黑洞

在 WSL 里做大包探测,这是最关键的一步:

ping -M do -s 1472 -c 3 1.1.1.1
From 192.168.1.1 icmp_seq=1 Frag needed and DF set (mtu = 1480)
ping: sendmsg: Message too long

路由器亲口告诉你 路径 MTU = 1480,而网卡是 1500——确诊。修复与固化:

# 立即生效
sudo ip link set dev eth0 mtu 1420

# 验证(注意:ping -s 是载荷,整包 = 载荷 + 28;接口 MTU 1420 时最大载荷是 1392)
ping -M do -s 1392 -c 3 1.1.1.1

# 永久固化:/etc/wsl.conf 的 [boot] 段,每次启动自动执行
[boot]
systemd=true
command = ip link set dev eth0 mtu 1420

为什么是 1420 而不是实测的 1480?因为路径 MTU 会变——PPPoE 是 1492、WireGuard 隧道默认 1420、开 TUN 全局代理还会更小。1420 是 WireGuard 官方默认值,留足余量,代价只是每包约 5% 的头部开销。1480 修的是今天的病,1420 防的是以后复发。

顺带排除两个常见误判:

不是 DNS 污染:用阿里(223.5.5.5)、腾讯(119.29.29.29)、114、Google DNS 分别解析,结果完全一致且落在 Cloudflare 正式地址段,就没有污染。污染的特征是国内外 DNS 返回不同结果、TLS 证书校验失败,而不是”传到一半才断”。
udev 规则在 WSL2 里通常无效:eth0 在 udev 启动前就已创建,规则没机会触发,别浪费时间在这条路上。

第三步:让 WSL 用上 Windows 代理

# NAT 模式下,默认网关就是 Windows 宿主机
WINHOST=$(ip route show default | awk '{print $3}')
export https_proxy=http://$WINHOST:10808 http_proxy=http://$WINHOST:10808

# 测速验证
curl -s --max-time 20 -o /dev/null -w "HTTP %{http_code}, %{speed_download} B/s\n" \
  -r 0-2097151 https://github.com

前提:代理软件必须勾选”允许来自局域网的连接”(v2rayN 在参数设置里),否则 WSL 的请求会被拒绝。我的实测:修复 MTU 前下载只有 44KB/s 且随时中断,修复 + 挂代理后 git clone 912MiB 跑出了 7.2MB/s。

注意:国内模型服务(MiMo / DeepSeek / Kimi / GLM)调用时要 unset https_proxy http_proxy,走代理反而可能更慢。

第四步:官方源安装 Hermes Agent

坚持不用国内镜像的话,走官方 GitHub 仓库手动安装:

# 1. 安装 uv(下载失败会自动切备用源,重跑即可)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env

# 2. 克隆官方仓库(--recurse-submodules 必须带上)
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 3. Python 3.11 虚拟环境 + 完整依赖
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"
uv pip install -e ".[all]"

# 4. 全局命令
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# 5. 初始化配置目录
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env

# 6. 体检(首次会提示配置 v0→vN,执行 --fix 自动迁移)
hermes doctor --fix

小坑:hermes version 在 0.21.x 里不存在,查版本用 hermes --version。

第五步:接入小米 MiMo Token Plan

小米官方文档提供了 Hermes Agent 专属接入页。Token Plan 的关键参数:

项目	值
Base URL(OpenAI 兼容)	`https://token-plan-cn.xiaomimimo.com/v1`(区域以订阅页为准,cn/sgp/ams)
API Key 格式	`tp-` 开头
推荐模型	`mimo-v2.5-pro`(旗舰纯文本)/ `mimo-v2.5`(支持图片),1M 上下文
环境变量	`XIAOMI_API_KEY`、`XIAOMI_BASE_URL`

推荐用专用命令(比完整向导稳——hermes setup 默认首项是 Nous Portal,直接回车会触发 OAuth 登录,而 WSL 里弹不出浏览器):

unset https_proxy http_proxy   # MiMo 国内直连,不要挂代理
hermes model
# 方向键选中 Xiaomi MiMo → 填入 tp- 开头的 Key
# Base URL 填 https://token-plan-cn.xiaomimimo.com/v1
# 默认模型选 mimo-v2.5 或 mimo-v2.5-pro

或者完全非交互式:

hermes config set model.provider custom
hermes config set model.base_url "https://token-plan-cn.xiaomimimo.com/v1"
hermes config set model.api_key "tp-你的Key"
hermes config set model.default mimo-v2.5-pro

最后 hermes doctor,看到 All checks passed! 即完成,hermes 启动对话。

第六步:启用 Web 仪表盘

命令行用爽了之后,可以再把 Web 控制台(hermes dashboard)跑起来——聊天记录、会话管理、模型切换、技能和定时任务都在浏览器里点。它需要 Node.js 构建前端,而 WSL 默认没有,首次运行会直接报缺 Node:

# 1. 安装 Node.js 22.x(NodeSource 官方源)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 2. 构建前端(在仓库的 web 目录)
cd ~/hermes-agent/web
npm install

# 3. 构建完成,启动仪表盘
npm run build
hermes dashboard

hermes dashboard 会输出一个 http://localhost:xxxx 地址,直接在 Windows 浏览器里打开即可——WSL2 会自动把 localhost 端口转发到宿主机,不需要任何额外配置。界面上能看到模型连接状态(右上角 LIVE 绿标)、可用工具/技能清单和历史会话。

三个注意点:

npm install 结束时提示的 “N vulnerabilities” 是开发依赖的常规警告,本地仪表盘不暴露公网,直接忽略;千万不要跑 npm audit fix --force,它会强升依赖版本,很可能把构建搞坏。
Vite 构建时关于 __dirname 的警告是无害的写法建议,不用处理。
hermes dashboard 是前台进程,Ctrl+C 即停止;以后更新 Hermes 版本(git pull + 重装依赖)后,记得回到 web 目录重跑 npm install && npm run build,否则仪表盘还是旧版前端。

故障判读速查表

现象	结论
握手成功但下载中断 / 速度骤降	MTU 黑洞,网卡设 1420
国内外 DNS 解析一致且是 Cloudflare 段	排除 DNS 污染(挂 CF 的域名客户端无法绕过)
Cloudflare 522 错误	源站宕机,客户端侧无解,等恢复
WSL 直连慢但 Windows 直连快	WSL 没走代理,指宿主机 IP
`wsl.conf` 的 `[boot]` 无效 / `systemctl` 报 not booted with systemd	WSL 版本过老,先 `wsl --update`
访问宿主机代理报 Connection refused	代理软件未开启”允许来自局域网的连接”
`hermes dashboard` 报缺 Node.js	WSL 没装 Node,NodeSource 源装 22.x
仪表盘启动但前端是旧版 / 页面空白	更新后没重新 `npm run build`,回到 web 目录重跑

写在最后

这趟排障最大的收获是建立了”分层排除”的直觉:先 DNS(五路对照)、再 TLS 行为(握手成功与否区分污染与黑洞)、再包长(大包 ping 定位 MTU)、最后代理链路。每一层都有确定性的判据,而不是靠换玄学配置碰运气。祝各位安装顺利。