ByteNoteByteNote
字

字节笔记本

2026年6月21日

hermes教程-Windows (WSL2) 指南

#Claude Code
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

为什么选择 WSL2（而非原生 Windows）

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 虚拟机。大多数困惑源于不确定自己当前处于哪一侧。

本指南涵盖与 Hermes 相关的拆分部分：安装 WSL2、在 Windows 和 Linux 之间传输文件、双向网络连接，以及人们实际遇到的陷阱。

信息 — 简体中文

本页同时维护了最小安装路径的中文版指南——通过右上角的语言菜单切换，选择简体中文。

为什么选择 WSL2（而非原生 Windows）

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

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

WSL2 的实际后果：

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

安装 WSL2

从管理员 PowerShell 或 Windows Terminal 运行：

powershell
wsl --install

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

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

powershell
wsl --list --verbose

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

powershell
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 上，在发行版内部启用一次：

bash
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 中运行：

powershell
wsl --shutdown

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

上面的 metadata 挂载选项很重要——没有它，/mnt/c/... 上的文件无法存储真正的 Linux 权限位，这会破坏诸如在 Windows 路径下对脚本执行 chmod +x 等操作。

在 WSL 内部安装 Hermes

打开 WSL2 shell 后：

bash
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/...）。
  • 你的模型、数据集、虚拟环境——Linux 侧。

遵循此规则的好处：

  • 快速 I/O。 对 /mnt/c/... 的操作通过 9P 进行，比原生 ext4 慢 10–100 倍。在 ~/code 下感觉瞬间完成的 10k 文件仓库的 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 运行：

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

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

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

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

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

在两个世界之间转换路径：

bash
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 配置：

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

对于已经包含 CRLF 的文件：

bash
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 在轻量级虚拟机中运行，拥有自己的网络栈。这意味着 WSL 内部的 localhost 与 Windows 上的 localhost 不同——从网络角度来看，它们是两个独立的主机。你需要为每个服务决定流量流向哪个方向，并选择正确的桥接。

有两种常见情况。

情况 1 — WSL 中的 Hermes 与 Windows 上的服务通信

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

相关操作指南位于提供者指南中：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 服务器（由 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 服务通常可以从 Windows 通过 http://localhost:PORT 访问。如果不行：

  • 在 WSL 内部显式绑定到 0.0.0.0。
  • 使用 ip -4 addr show eth0 | grep inet 查找 WSL 虚拟机的 IP，然后从 Windows 访问该 IP。

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

这是真正的痛点。流量流经 局域网设备 → Windows 主机 → WSL 虚拟机，你需要设置两个跳点：

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

  2. 端口转发 Windows → WSL 虚拟机。 在镜像模式下这是自动的。在 NAT 模式下，你需要手动为每个端口执行此操作，在管理员 PowerShell 中：

    powershell
    undefined

获取 WSL 虚拟机的当前 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

text

稍后使用 `netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080` 删除。

3. **将局域网设备指向 `http://<windows-lan-ip>:8080`。**

由于在 NAT 模式下 WSL 虚拟机 IP 在每次重启后都会漂移，一次性规则只能持续到下一次 `wsl --shutdown`。对于任何持久性需求，要么使用镜像模式，要么将端口代理步骤放入一个在 Windows 登录时运行的脚本中。

对于来自云消息提供者（Telegram `setWebhook`、Slack 事件等）的 webhook，不要与端口转发较劲——使用 `cloudflared` 隧道。请参阅 [webhook 指南](/user-guide/messaging/webhooks)。

## 在 Windows 上长期运行 Hermes 服务

Hermes [工具网关](/user-guide/features/tool-gateway) 和 API 服务器是长期运行的进程。在 WSL2 中，你有几种选项来保持它们运行。

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

如果你只想要一个双击启动器来打开交互式 Hermes shell，可以在 Windows 侧创建它，并让它跳转到 WSL：

1. 右键单击 Windows 桌面，选择 **新建 -> 快捷方式**。
2. 对于目标，使用你的发行版名称（如果需要，替换 `Ubuntu`）：

```text
wt.exe -w 0 -p "Ubuntu" wsl.exe -d Ubuntu --cd ~ -- bash -ic "hermes"
  1. 将其命名为类似 Hermes 的明显名称。

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

可选优化：

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

在 WSL 内部使用 systemd（推荐）

如果你按照上述设置部分启用了 systemd，hermes gateway 和 API 服务器的工作方式与在任何 Linux 机器上相同。使用网关设置向导：

bash
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 原生本地模型服务器（Windows 版 Ollama、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）。按需修复：

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

下一步

Claude Code
上一篇

hermes教程-Windows（原生）指南

下一篇

hermes教程-Windows (WSL2) 指南

分享: