Windows (WSL2) 指南

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

何时选择 WSL2 而非原生：

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

何时原生即可（或更好）：

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

在 WSL2 中，实际上涉及两台计算机：你的 Windows 主机，以及由 WSL 管理的 Linux 虚拟机。大多数困惑源于不确定当前处于哪一端。

本指南涵盖了专门影响 Hermes 的那些分割部分：安装 WSL2、在 Windows 和 Linux 之间传输文件、双向网络通信，以及人们实际遇到的陷阱。

简体中文

此页面维护了一份最小化安装路径的中文语言 walkthrough —— 通过语言菜单（右上角）切换并选择简体中文。

为什么选择 WSL2（相对于原生 Windows）

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

WSL2 在轻量级 VM 中运行真正的 Linux 内核，因此其中的 Hermes 本质上与在 Ubuntu 上运行相同。当你需要真正的 POSIX 环境时，这非常有价值：fork、/tmp、UNIX socket、信号语义、基于 PTY 的终端、像 bash/zsh 这样的 shell，以及像 rg、git、ffmpeg 这样行为与 Linux 上一致的工具。

WSL2 的实际影响：

• Hermes CLI、网关、会话、记忆、技能和工具运行时都位于 Linux VM 内部。
• 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 设置指南。

启用 systemd（推荐）

使用 systemd 可以更轻松地管理 hermes 网关（以及你希望保持运行的任何其他内容）。在现代 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://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes

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

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

这是最让人困扰的部分。这里有两个文件系统，你放置文件的位置至关重要——关乎性能、正确性以及工具的可见性。

两个方向

方向	内部路径	你使用的路径
从 WSL 看到的 Windows 磁盘	C:\Users\you\Documents	/mnt/c/Users/you/Documents
从 Windows 看到的 WSL 磁盘	/home/you/code	\\wsl$\Ubuntu\home\you\code（或在较新版本中为 \\wsl.localhost\Ubuntu\...）

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

放置 Hermes 和你的项目的位置

经验法则：将所有 Linux 相关内容保留在 Linux 文件系统中。

• 你的 Hermes 安装目录（~/.hermes/）—— 位于 Linux 侧。安装程序已经默认这样处理。
• 你在 WSL 中操作的 git 仓库 —— 位于 Linux 侧（~/code/...、~/projects/...）。
• 你的模型、数据集、虚拟环境（venvs）—— 位于 Linux 侧。

遵循此规则带来的好处：

• 快速的 I/O。 对 /mnt/c/... 的操作需要通过 9P 协议，速度比原生 ext4 慢 10–100 倍。在 ~/code 下瞬间完成的包含 1 万个文件的仓库的 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\<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     # once — gives you wslview, wslpath, wslopen, etc.
wslview ~/reports/output.pdf    # opens with the Windows default handler
explorer.exe .                  # opens the current WSL dir in Windows Explorer

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

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 在具有自己网络栈的轻量级 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（或你的局域网）上的内容与 WSL 中的 Hermes 通信

这是反向方向，其他地方的文档较少，但以下场景需要这样做：

• 从 Windows 浏览器使用 Hermes Web 仪表板。
• 从 Windows 侧工具使用 OpenAI 兼容 API 服务器（当 API_SERVER_ENABLED=true 时由 hermes gateway 暴露）。参见 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 访问该 IP。

子情况 2b：来自局域网上的其他设备（手机、平板、另一台 PC）

这是真正麻烦的地方。流量流向为 局域网设备 → Windows 主机 → WSL VM，你需要设置这两跳：

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

2. 端口转发 Windows → WSL VM。 在镜像模式下这是自动的。在 NAT 模式下，你必须在管理员 PowerShell 中手动按端口进行配置：

   # Grab the WSL VM's current IP (it changes on every WSL restart under NAT)
   $wslIp = (wsl hostname -I).Trim().Split(' ')[0]
   
   # Forward Windows port 8080 → WSL:8080
   netsh interface portproxy add v4tov4 `
     listenaddress=0.0.0.0 listenport=8080 `
     connectaddress=$wslIp connectport=8080
   
   # Allow it through Windows Firewall
   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 中，你有几种选项来保持它们运行。

用于快速打开 Hermes 的桌面快捷方式

如果你只想要一个双击即可启动的交互式 Hermes shell 启动器，请在 Windows 端创建它，并让它跳转到 WSL：

1. 右键单击 Windows 桌面并选择 新建 -> 快捷方式。

2. 对于目标位置，使用你的发行版名称（如有需要，替换 Ubuntu）：

   wt.exe -w 0 -p "Ubuntu" wsl.exe -d Ubuntu --cd ~ -- bash -ic "hermes"

3. 将其命名为显而易见的名称，例如 Hermes。

这将打开 Windows Terminal，启动你的 WSL 发行版，将你置于 Linux 主目录中，并启动 Hermes。如果 hermes 尚未在 PATH 中，请手动打开一次 WSL 并运行 source ~/.bashrc，或者在项目检出目录中将命令替换为 uv run hermes。

可选优化：

• 自定义图标： 打开 属性 -> 更改图标，并将其指向 .ico 文件，例如仓库中的 Hermes favicon。
• 固定启动器： 一旦快捷方式正常工作，将其固定到“开始”菜单或任务栏，这样你就无需再次浏览查找。

在 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 直通（本地模型）

自 WSL 内核 5.10.43+ 起，WSL2 原生支持 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 驱动程序使用 GPU 的 Windows 原生 本地模型服务器（适用于 Windows 的 Ollama、LM Studio），你根本不需要 WSL GPU 直通——只需遵循上面的情况 1，并从 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 路径”警告。 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 文件时速度缓慢。 当从 Windows 访问文件时，Defender 会通过 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 暴露给网络其余部分的长期运行服务。