Windows（WSL2）指南

Hermes Agent 现在同时支持 Windows 原生和 WSL2。本页介绍 WSL2 路径；关于原生 PowerShell 安装，请参阅专门的 Windows（原生）指南。

何时选择 WSL2 而非原生：

• 你想使用仪表盘的嵌入式终端（/chat 标签）——该面板需要 POSIX PTY，仅限 WSL2。
• 你正在进行大量 POSIX 相关的开发工作，希望 Hermes 会话与你的开发工具共享相同的文件系统/路径。
• 你已有 WSL2 环境，不想维护第二个安装。

何时使用原生（或更好）：

• 交互式聊天、网关（Telegram/Discord 等）、定时调度器、浏览器工具、MCP 服务器以及大多数 Hermes 功能都在 Windows 上原生运行。
• 你不想每次引用文件或打开 URL 时都要考虑跨越 WSL↔Windows 边界。

在 WSL2 中，实际上有两个计算机在起作用：你的 Windows 宿主机，以及由 WSL 管理的 Linux VM。大多数困惑来自于不确定你在任何时刻处于哪个环境中。

本指南涵盖了这种拆分中特别影响 Hermes 的部分：安装 WSL2、在 Windows 和 Linux 之间传递文件、双向网络以及人们实际遇到的陷阱。

:::info 简体中文 本页维护了一个最小安装路径的中文教程——通过右上角的语言菜单切换并选择简体中文。 :::

为什么选择 WSL2（vs. Windows 原生）

Windows 原生安装直接在 Windows 中运行：你的 Windows 终端（PowerShell、Windows Terminal 等）、Windows 文件系统路径（C:\\Users\\…）和 Windows 进程。Hermes 使用 Git Bash 运行 shell 命令，这是 Claude Code 和其他 agent 今天在 Windows 上的处理方式——它绕过了 POSIX vs Windows 的差距，而无需完全重写。

WSL2 在一个轻量级 VM 中运行真正的 Linux 内核，因此其中的 Hermes 本质上与在 Ubuntu 上运行相同。当你需要真正的 POSIX 环境时，这很有价值：fork、/tmp、UNIX 套接字、信号语义、PTY 支持的终端、bash/zsh 等 shell，以及 rg、git、ffmpeg 等工具，它们的行为与在 Linux 上一致。

WSL2 的实际影响：

• Hermes CLI、网关、会话、记忆、技能和工具运行时都位于 Linux VM 中。
• Windows 程序（浏览器、原生应用、带有登录配置文件的 Chrome）位于 VM 之外。
• 每次你希望两者通信时——共享文件、打开 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 设置指南了解该路径。

启用 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 shell 后：

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 网络协议桥接。这有真实的性能和语义后果。

放置 Hermes 和你的项目

经验法则：将所有 Linux 相关的东西放在 Linux 文件系统中。

• 你的 Hermes 安装（~/.hermes/）——Linux 侧。安装程序已经这样做了。
• 你从 WSL 工作的 git 仓库——Linux 侧（~/code/...、~/projects/...）。
• 你的模型、数据集、虚拟环境——Linux 侧。

遵循此规则的好处：

• 快速 I/O。 对 /mnt/c/... 的操作经过 9P，比原生 ext4 慢 10–100 倍。在一个有 1 万个文件的仓库上，git status 在 ~/code 下感觉瞬间完成，在 /mnt/c 下可能需要 15 秒以上。
• 正确的权限。 在 /mnt/c 上，Linux 权限位是最佳努力的模拟。诸如 ssh 拒绝密钥并显示”bad permissions”或 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\\<you>\\...。或者从 PowerShell：

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

从 WSL → 进入 Windows： 复制到 /mnt/c/Users/<you>/...，它会立即出现在 Windows 资源管理器中：

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

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

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

在两个宇宙之间转换路径：

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 进程具有驱动器号 cwd。

网络：WSL ↔ Windows

WSL2 在具有自己网络栈的轻量级 VM 中运行。这意味着 WSL 内部的 localhost 不同于 Windows 上的 localhost——从网络角度看，它们是两个独立的主机。对于每个服务，你需要决定流量流向哪个方向，并选择正确的桥接。

两种情况经常出现。

情况 1——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 防火墙解决方法）请点击上面的链接——不要重复。

情况 2——Windows 上（或你的 LAN）的某些东西与 WSL 中的 Hermes 通信

这是反向方向，在其他地方记录较少，但这是你需要的：

• 从 Windows 浏览器使用 Hermes Web 仪表盘。
• 从 Windows 侧工具使用 OpenAI 兼容的 API 服务器（由 hermes gateway 在 API_SERVER_ENABLED=true 时暴露）。参见 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 服务通常可以以 http://localhost:PORT 从 Windows 访问。如果不行：

• 在 WSL 内显式绑定到 0.0.0.0。
• 用 ip -4 addr show eth0 | grep inet 找到 WSL VM 的 IP，并从 Windows 访问该 IP。

子情况 2b：从你 LAN 上的另一个设备（手机、平板、另一台 PC）

这是真正的痛点。流量流动路径为 LAN 设备 → Windows 宿主机 → WSL VM，你需要设置两个跳点：

1. 在 WSL 内绑定所有接口。 在 127.0.0.1 上监听的进程永远无法从 VM 外部访问。使用 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. 将 LAN 设备指向 http://<windows-lan-ip>:8080。

因为 WSL VM IP 在 NAT 模式下每次重启都会漂移，一次性的规则只在下次 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 的 VM 只有在有东西使用它时才保持存活。要让你的网关无需打开终端窗口即可访问，通过任务计划程序在 Windows 登录时启动一个 WSL 进程：

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

这样保持 VM 存活，因此由 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 直通——只需按照上面的情况 1 操作，从 WSL 通过网络访问它。

常见陷阱

对我 Windows 托管的 Ollama / LM Studio 显示”连接被拒绝”。 参见 WSL2 网络。90% 的情况下，服务器绑定到了 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 路径”警告。 Hermes 的 cwd 位于 Linux 文件系统中，Windows cmd.exe 不知道如何处理。为该会话从 /mnt/c/... 启动 Hermes，或使用一个包装器在调用 Windows 可执行文件之前 cd 到 Windows 可访问的路径。

休眠/睡眠后的时钟漂移。 WSL2 的时钟在宿主机从睡眠中恢复后可能滞后几分钟，这会破坏任何基于证书的东西（OAuth、HTTPS API）。按需修复：

sudo hwclock -s

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

启用镜像模式或连接 VPN 后 DNS 停止工作。 镜像模式将主机网络设置代理到 WSL 中——如果 Windows DNS 不正常（VPN 分流、企业解析器），WSL 会继承这种状态。解决方法：手动覆盖 resolv.conf（在 /etc/wsl.conf 中设置 generateResolvConf=false，然后编写你自己的 /etc/resolv.conf，使用 1.1.1.1 或你的 VPN 的 DNS）。

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

Windows Defender 对 WSL 文件扫描缓慢。 Defender 在从 Windows 访问时通过 9P 桥接扫描文件，这放大了 /mnt/c 风格跨边界访问的缓慢。如果你只从 WSL 内部触碰 WSL 文件，这不重要。如果你频繁使用 Windows 工具访问 \\\\wsl$\\...，考虑将 WSL 发行版路径从实时扫描中排除。

磁盘空间不足。 WSL2 将其 VM 磁盘存储为 %LOCALAPPDATA%\\Packages\\... 下的稀疏 VHDX。它会增长但在删除文件时不会自动缩小。要回收空间：wsl --shutdown，然后从管理员 PowerShell 运行 Optimize-VHD -Path <path-to-ext4.vhdx> -Mode Full（需要 Hyper-V 工具）——或者使用 WSL 文档中记录的更简单的 diskpart 路径。

接下来去哪里

• 安装——实际安装步骤（Linux/WSL2/Termux 都使用相同的安装程序）。
• 集成 → 提供商 → WSL2 网络——本地模型服务器的规范网络深入指南。
• MCP 指南 → WSL → Windows Chrome——从 WSL 中的 Hermes 控制你已登录的 Windows Chrome。
• 工具网关 和 Web 仪表盘——你最常需要从 WSL 暴露到网络其余部分的长期运行服务。