Windows (WSL2) 指南

Hermes Agent 在 Linux 和 macOS 上开发和测试。不支持 Windows 原生运行——在 Windows 上，你需要在 WSL2（Windows Subsystem for Linux，第 2 版）内运行 Hermes。这意味着实际上有两台"电脑"同时运行：Windows 主机和 WSL 管理的 Linux 虚拟机。大多数困惑来自于不清楚自己当前在哪一个环境中操作。

本指南涵盖这种分离架构中专门影响 Hermes 的部分：安装 WSL2、在 Windows 和 Linux 之间传输文件、双向网络通信，以及实际会遇到的各种坑。

简体中文

本页面提供简体中文版完整指南，即为当前您正在阅读的内容。

为什么选择 WSL2（而不是"直接用 Windows"）

Hermes 假设运行在 POSIX 环境中：fork、/tmp、UNIX 套接字、信号语义、PTY 支持的终端，以及 rg、git、ffmpeg 等在 Linux 上才有正确行为的工具。将这些全部改写为 Windows 原生实现几乎等同于完整移植——而 WSL2 提供了一个轻量级虚拟机中的真实 Linux 内核，在其中运行 Hermes 与在 Ubuntu 上运行几乎完全一样。

这一选择的实际影响：

• Hermes CLI、网关、会话、记忆、技能和工具运行时都在 Linux 虚拟机内。
• Windows 程序（浏览器、原生应用、带登录状态的 Chrome）在虚拟机外。
• 每次需要让两者通信——共享文件、打开 URL、控制 Chrome、访问本地模型服务器、将 Hermes 网关暴露给手机——都需要跨越这条边界。这些边界正是本指南要讲解的内容。

安装 WSL2

从管理员 PowerShell 或 Windows Terminal 执行：

wsl --install

在全新的 Windows 10 22H2+ 或 Windows 11 系统上，此命令会安装 WSL2 内核、虚拟机平台功能以及默认的 Ubuntu 发行版。按提示重启。重启后 Ubuntu 会打开并要求设置 Linux 用户名和密码——这是一个新的 Linux 用户，与你的 Windows 账户无关。

验证你确实在使用 WSL2（而非旧版 WSL1）：

wsl --list --verbose

应看到 VERSION 2。如果某个发行版显示 VERSION 1，执行转换：

wsl --set-version Ubuntu 2
wsl --set-default-version 2

Hermes 在 WSL1 上无法可靠运行——WSL1 会即时转译 Linux 系统调用，某些行为（procfs、信号、网络）与真实 Linux 存在差异。

发行版选择

Ubuntu（LTS）是我们的测试环境。Debian 也可以使用。Arch 和 NixOS 对有需要的用户同样适用，但一键安装脚本假设基于 Debian 的 apt 系统——Nix 路径请参阅 Nix 安装指南。

启用 systemd（推荐）

Hermes 网关（以及其他需要持续运行的服务）使用 systemd 管理更为方便。在现代 WSL 中，在你的发行版内执行一次即可：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true

[automount]
options = "metadata,umask=22,fmask=11"
EOF

然后从 PowerShell 执行：

wsl --shutdown

重新打开 WSL 终端。ps -p 1 -o comm= 应输出 systemd。

上述的 metadata 挂载选项很重要——没有它，/mnt/c/... 上的文件无法存储真实的 Linux 权限位，这会导致 Windows 路径下的脚本 chmod +x 无效等问题。

在 WSL 内安装 Hermes

打开 WSL2 终端后：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
hermes

安装程序将 WSL2 视为普通 Linux——不需要任何 WSL 特定操作。完整布局请参阅安装。

文件系统：跨越 Windows ↔ WSL2 边界

这是最容易让人困惑的部分。有两个文件系统，文件放在哪里至关重要——影响性能、正确性以及哪些工具能访问到。

两个方向

方向	内部路径	使用路径
Windows 磁盘，从 WSL 访问	C:\Users\you\Documents	/mnt/c/Users/you/Documents
WSL 磁盘，从 Windows 访问	/home/you/code	\\wsl$\Ubuntu\home\you\code（较新版本用 \\wsl.localhost\Ubuntu\...）

两者都真实存在，都可以使用，但不是同一个文件系统——底层通过 9P 网络协议桥接。这有实际的性能和语义影响。

文件应该放在哪里

原则：将所有 Linux 相关内容保留在 Linux 文件系统内。

• Hermes 安装目录（~/.hermes/）——Linux 端。安装程序已自动处理。
• 你在 WSL 中开发的 git 仓库——Linux 端（~/code/...、~/projects/...）。
• 模型、数据集、虚拟环境——Linux 端。

遵守此原则的好处：

• 快速 I/O。 /mnt/c/... 上的操作经过 9P，比原生 ext4 慢 10–100 倍。一个 1 万个文件的仓库在 ~/code 下 git status 几乎瞬间完成，在 /mnt/c 下可能需要 15 秒以上。
• 正确的权限。 Linux 权限位在 /mnt/c 上是尽力模拟。ssh 因"权限不当"拒绝密钥、chmod +x 静默失败等问题很常见。
• 可靠的文件监听器。 跨 9P 的 inotify 不稳定——开发服务器、测试运行器等文件监听器在 /mnt/c 上常常漏掉变更。
• 无大小写敏感问题。 Windows 路径默认不区分大小写；Linux 区分。同时包含 Readme.md 和 README.md 的项目在不同端行为不同。

只在必须让文件存在于 Windows 端时才使用 /mnt/c——例如需要用 Windows GUI 应用打开，或 Windows Chrome 的 DevTools MCP 需要当前目录为 Windows 可访问路径。

在两端之间传输文件

从 Windows 传到 WSL： 最简单的方式是打开资源管理器，在地址栏输入 \\wsl.localhost\Ubuntu，然后拖拽到 \home\<你>\...。或从 PowerShell：

wsl cp /mnt/c/Users/you/Downloads/file.pdf ~/incoming/

从 WSL 传到 Windows： 复制到 /mnt/c/Users/<你>/...，Windows 资源管理器会立即看到：

cp ~/reports/output.pdf /mnt/c/Users/you/Desktop/

在 Windows 应用（GUI 编辑器、浏览器等）中打开 WSL 文件： 使用 explorer.exe 或 wslview：

sudo apt install wslu     # 一次性安装——提供 wslview、wslpath、wslopen 等工具
wslview ~/reports/output.pdf    # 用 Windows 默认程序打开
explorer.exe .                  # 在 Windows 资源管理器中打开当前 WSL 目录

在两个环境之间转换路径：

wslpath -w ~/code/project        # → \\wsl.localhost\Ubuntu\home\you\code\project
wslpath -u 'C:\Users\you'        # → /mnt/c/Users/you

行尾符、BOM 和 git

如果你用 Windows 编辑器在 Windows 端编辑文件，可能会产生 CRLF 行尾符。当 Linux 端的 bash 或 Python 读取这些文件时，shell 脚本会因 bad interpreter: /bin/bash^M 报错，Python 也可能在带 BOM 的 .env 文件上失败。

解决方法是在 WSL 内（不是 Windows 上）配置合理的 git 设置：

git config --global core.autocrlf input
git config --global core.eol lf

对于已有 CRLF 的文件：

sudo apt install dos2unix
dos2unix path/to/script.sh

"仓库应该克隆在 WSL 内还是 /mnt/c？"

克隆到 WSL 内。始终如此，除非有特殊原因。典型的 Hermes 工作流（hermes chat、使用 rg/ripgrep 搜索仓库的工具调用、文件监听器、后台网关）在 ~/code/myrepo 下会比在 /mnt/c/Users/you/myrepo 下快得多，也更稳定。

一个例外：启动 Windows 二进制文件的 MCP 桥接。 如果你通过 cmd.exe 使用 chrome-devtools-mcp（参见 MCP 指南：WSL → Windows Chrome），当 Hermes 的当前工作目录为 ~ 时，Windows 可能会提示 UNC 警告。这种情况下，从 /mnt/c/ 下的某个目录启动 Hermes，使 Windows 进程获得一个驱动器字母格式的工作目录。

网络：WSL ↔ Windows

WSL2 在轻量级虚拟机中运行，拥有独立的网络栈。这意味着 WSL 内的 localhost 与 Windows 上的 localhost 不是同一个地址——从网络角度看，它们是两台独立的主机。对于每个服务，你需要确定流量方向并选择正确的桥接方式。

有两个场景经常出现。

场景一：WSL 内的 Hermes 访问 Windows 上的服务

最常见的情况：你在 Windows 上运行 Ollama、LM Studio 或 llama-server，而 WSL 内的 Hermes 需要访问它。

此场景的完整说明请参阅提供商指南：WSL2 本地模型网络配置 →

简要说明：

• Windows 11 22H2+： 启用镜像网络模式（在 %USERPROFILE%\.wslconfig 中设置 networkingMode=mirrored，然后执行 wsl --shutdown）。这样 localhost 在两个方向上都可用。
• Windows 10 或旧版本： 使用 Windows 主机 IP（WSL 虚拟网络的默认网关），并确保 Windows 上的服务器绑定到 0.0.0.0 而非仅 127.0.0.1。通常还需要在 Windows 防火墙中添加端口规则。

完整表格（Ollama / LM Studio / vLLM / SGLang 绑定地址、防火墙一行命令、动态 IP 助手、Hyper-V 防火墙绕过方案）请参阅上方链接——此处不再重复。

场景二：Windows（或局域网）访问 WSL 内的 Hermes

这是反向操作，其他文档较少涉及，但以下场景会用到：

• 从 Windows 浏览器使用 Hermes Web 控制台。
• 从 Windows 端工具使用 API 服务器（hermes api）。
• 测试消息网关（Telegram、Discord 等），此类平台会 ping 本地 webhook URL——通常推荐使用 cloudflared/ngrok 而非直接端口转发。

子场景 2a：从 Windows 主机本身访问

在启用了镜像模式的 Windows 11 22H2+ 上，无需任何配置。WSL 内绑定到 0.0.0.0:8080（甚至 127.0.0.1:8080）的进程，Windows 浏览器可以通过 http://localhost:8080 访问。WSL 会自动将绑定发布回主机。

在 NAT 模式（Windows 10 / 旧版 Windows 11）下，WSL2 默认的"localhost 转发"通常会将 Linux 端的 127.0.0.1 绑定转发到 Windows 的 localhost，所以以 --host 127.0.0.1 启动的 Hermes 服务通常可以从 Windows 通过 http://localhost:PORT 访问。如果不行：

• 在 WSL 内显式绑定到 0.0.0.0。
• 使用 ip -4 addr show eth0 | grep inet 获取 WSL VM 的 IP，然后从 Windows 访问该地址。

子场景 2b：从局域网其他设备访问（手机、平板、另一台电脑）

这是真正棘手的部分。流量路径为：局域网设备 → Windows 主机 → WSL VM，你需要配置两段跳转：

1. 在 WSL 内绑定所有接口。 监听 127.0.0.1 的进程永远无法从虚拟机外部访问。使用 0.0.0.0。

2. 设置 Windows → WSL VM 的端口转发。 镜像模式下自动完成。NAT 模式下需要在管理员 PowerShell 中手动设置，每个端口单独配置：

   # 获取 WSL VM 当前 IP（NAT 模式下每次 WSL 重启后会变化）
   $wslIp = (wsl hostname -I).Trim().Split(' ')[0]
   
   # 转发 Windows 8080 端口 → WSL:8080
   netsh interface portproxy add v4tov4 `
     listenaddress=0.0.0.0 listenport=8080 `
     connectaddress=$wslIp connectport=8080
   
   # 在 Windows 防火墙中放行该端口
   New-NetFirewallRule -DisplayName "Hermes WSL 8080" `
     -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow

   之后通过以下命令删除规则：netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080。

3. 让局域网设备访问 http://<windows-lan-ip>:8080。

由于 NAT 模式下 WSL VM 的 IP 在每次重启后会变化，一次性配置的规则在下次 wsl --shutdown 后就会失效。如需持久配置，要么使用镜像模式，要么将端口转发步骤写入 Windows 登录时运行的脚本。

对于来自云端消息提供商的 webhook（Telegram setWebhook、Slack 事件等），建议使用 cloudflared 隧道，而非与端口转发较劲。详见 webhook 指南。

在 Windows 上长期运行 Hermes 服务

Hermes 工具网关和 API 服务器是长时间运行的进程。在 WSL2 中有几种方式保持它们持续运行。

在 WSL 内使用 systemd（推荐）

如果你按照前述步骤启用了 systemd，hermes gateway 和 API 服务器的使用方式与任何 Linux 机器完全相同。使用网关安装向导：

hermes gateway setup

它会提示安装 systemd 用户单元，使网关在 WSL 启动时自动运行。

让 WSL 在 Windows 登录时自动启动

WSL 的虚拟机只在有程序使用时保持运行。若要在不打开终端窗口的情况下保持网关可访问，可通过任务计划程序在 Windows 登录时启动 WSL 进程：

• 触发器： 用户登录时（你的账户）。
• 操作： 启动程序
  • 程序：C:\Windows\System32\wsl.exe
  • 参数：-d Ubuntu --exec /bin/sh -c "sleep infinity"

这会保持虚拟机运行，使 systemd 管理的网关持续工作。在 Windows 11 上，较新的 wsl --install --no-launch + 自动启动方案也可以；sleep infinity 是兼容性更好的通用方式。

GPU 直通（本地模型）

WSL2 自 WSL 内核 5.10.43+ 起原生支持 NVIDIA GPU——在 Windows 上安装标准 NVIDIA 驱动即可（不要在 WSL 内安装 Linux 版 NVIDIA 驱动），WSL 内的 nvidia-smi 就能识别 GPU。之后，CUDA 工具链、torch、vllm、sglang 和 llama-server 均可正常使用真实 GPU。

WSL2 内对 AMD ROCm 和 Intel Arc 的支持仍在发展中，超出了 Hermes 的测试范围——使用最新驱动可能可以工作，但我们没有推荐的配置方案。

如果你运行的是Windows 原生本地模型服务器（Ollama for Windows、LM Studio），它们已通过 Windows 驱动使用你的 GPU，完全不需要 WSL GPU 直通——只需按照场景一从 WSL 通过网络访问即可。

常见问题

连接 Windows 上的 Ollama / LM Studio 时提示"Connection refused"。 参阅 WSL2 网络配置。九成的情况是服务器绑定到了 127.0.0.1 而需要改为 0.0.0.0（Ollama：OLLAMA_HOST=0.0.0.0），或者缺少防火墙规则。

git status / hermes chat 在某个仓库下非常慢。 你可能在 /mnt/c/... 下工作。将仓库移到 ~/code/...（Linux 端），速度会有数量级的提升。

脚本报错 bad interpreter: /bin/bash^M。 Windows 编辑器引入了 CRLF 行尾符。执行 dos2unix script.sh，并在 WSL 的 git 配置中设置 core.autocrlf input。

通过 MCP 启动 Windows 二进制文件时提示"UNC paths are not supported"。 Hermes 的当前工作目录位于 Linux 文件系统内，Windows 的 cmd.exe 无法识别。将该会话的 Hermes 启动目录改为 /mnt/c/... 下的路径，或使用包装脚本在调用 Windows 可执行文件前先 cd 到 Windows 可访问的路径。

休眠/睡眠后出现时钟漂移。 WSL2 的时钟在主机从休眠中恢复后可能落后几分钟，这会导致任何基于证书的操作失败（OAuth、HTTPS API）。按需修复：

sudo hwclock -s

或安装 ntpdate 并在登录时运行。

启用镜像模式后或连接 VPN 时 DNS 停止工作。 镜像模式会将主机网络设置代理到 WSL——如果 Windows 的 DNS 有问题（VPN 分流隧道、企业 DNS），WSL 会继承这些问题。解决方法：手动覆盖 resolv.conf（在 /etc/wsl.conf 中设置 generateResolvConf=false，然后手动编写 /etc/resolv.conf，填入 1.1.1.1 或你的 VPN DNS）。

运行安装程序后找不到 hermes 命令。 安装程序通过 ~/.bashrc 将 ~/.local/bin 添加到 PATH。你需要执行 source ~/.bashrc（或打开新终端）才能在当前会话中生效。

Windows Defender 对 WSL 文件速度很慢。 Defender 在从 Windows 访问文件时会通过 9P 桥接进行扫描，放大了 /mnt/c 风格跨边界访问的慢速问题。如果你只在 WSL 内访问 WSL 文件，则没有影响。如果你频繁用 Windows 工具访问 \\wsl$\...，可以考虑将 WSL 发行版路径从实时扫描中排除。

磁盘空间不足。 WSL2 将虚拟机磁盘存储为 %LOCALAPPDATA%\Packages\... 下的稀疏 VHDX 文件。它会增长，但删除文件后不会自动收缩。回收空间的方法：先执行 wsl --shutdown，然后在管理员 PowerShell 中运行 Optimize-VHD -Path <ext4.vhdx路径> -Mode Full（需要 Hyper-V 工具）——或参阅 WSL 文档中更简单的 diskpart 方法。

下一步

• 安装 — 实际安装步骤（Linux/WSL2/Termux 使用相同的安装脚本）。
• 集成 → 提供商 → WSL2 网络配置 — 本地模型服务器的完整网络配置指南。
• MCP 指南 → WSL → Windows Chrome — 从 WSL 内的 Hermes 控制已登录的 Windows Chrome。
• 工具网关 和 Web 控制台 — 最常需要从 WSL 向网络暴露的长时服务。