上游开发与 CI 以 Linux / macOS 为主；在 Windows 上，官方推荐路径是 WSL2，而不是在 旧版原生 CMD/PowerShell 里直接跑完整 Hermes 栈。本页给出从 0 到可跑 hermes + Tool Gateway 的最短闭环。
何时选择 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 之间传输文件、双向网络连接，以及人们实际会遇到的陷阱。
为什么选择 WSL2（对比原生 Windows）
Section titled “为什么选择 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
Section titled “安装 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 2wsl --set-default-version 2Hermes 在 WSL1 上无法稳定运行 —— WSL1 通过即时翻译 Linux 系统调用来实现，某些行为（procfs、信号、网络）与真实 Linux 存在偏差。
我们主要在 Ubuntu (LTS) 上进行测试。Debian 也可以正常工作。Arch 和 NixOS 对有需求的用户也是可行的，但一键安装脚本假设系统是基于 Debian 的 apt 体系 —— 如果使用 Nix，请参考 Nix 设置指南。
启用 systemd（推荐）
Section titled “启用 systemd（推荐）”使用 systemd 可以更轻松地管理 Hermes 网关（以及任何你希望保持运行的服务）。在现代 WSL 中，请在发行版内部执行一次以下操作来启用它：
sudo tee /etc/wsl.conf >/dev/null <<'EOF'[boot]systemd=true
[interop]enabled=trueappendWindowsPath=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
Section titled “在 WSL 内部安装 Hermes”打开 WSL2 Shell 后运行：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashsource ~/.bashrchermes安装程序会将 WSL2 视为普通的 Linux 环境 —— 不需要任何针对 WSL 的特殊操作。完整的布局说明请参阅 安装页面。
文件系统：跨越 Windows ↔ WSL2 边界
Section titled “文件系统：跨越 Windows ↔ WSL2 边界”这是最容易让人困惑的部分。这里存在 两个文件系统，你将文件放在哪里至关重要 —— 这关乎性能、正确性以及工具的可见性。
| 方向 | WSL 内部路径 | 你使用的路径 |
|---|---|---|
| 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 和你的项目放在哪里
Section titled “应该把 Hermes 和你的项目放在哪里”经验法则：将所有 Linux 风格的内容留在 Linux 文件系统内部。
- 你的 Hermes 安装目录 (
~/.hermes/) —— 放在 Linux 侧。安装程序默认会这样做。 - 你从 WSL 操作的 Git 仓库 —— 放在 Linux 侧（如
~/code/...或~/projects/...）。 - 你的模型、数据集、虚拟环境（venvs） —— 放在 Linux 侧。
遵循此规则的好处：
- 极速 I/O：在
/mnt/c/...上的操作通过 9P 协议，比原生 ext4 慢 10–100 倍。在~/code下秒开的万级文件仓库，如果在/mnt/c下执行git status可能需要 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 可访问的路径。
文件往来传输
Section titled “文件往来传输”- 从 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 . # 在 Windows 资源管理器中打开当前 WSL 目录- 在两个世界之间转换路径：
wslpath -w ~/code/project # → `\\wsl.localhost\Ubuntu\home\you\code\project`wslpath -u 'C:\Users\you' # → `/mnt/c/Users/you`换行符、BOM 和 Git
Section titled “换行符、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 inputgit config --global core.eol lf对于已经存在 CRLF 的文件：
sudo apt install dos2unixdos2unix path/to/script.sh是在 WSL 内部克隆还是在 /mnt/c 下克隆？
Section titled “是在 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
Section titled “网络：WSL ↔ Windows”WSL2 运行在一个拥有独立网络栈的轻量级虚拟机中。这意味着 WSL 内部的 localhost 与 Windows 上的 localhost 不是同一个 —— 从网络角度来看，它们是两个独立的主机。你需要根据每个服务的具体情况，决定流量的流向并选择正确的桥接方式。
通常会出现以下两种情况：
情况 1 —— WSL 中的 Hermes 访问 Windows 上的服务
Section titled “情况 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
Section titled “情况 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 宿主机本身访问
Section titled “子情况 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:端口 访问。如果无法访问：
- 在 WSL 内部显式绑定到
0.0.0.0。 - 通过
ip -4 addr show eth0 | grep inet查找 WSL 虚拟机的 IP，并在 Windows 中访问该 IP。
子情况 2b：从局域网中的其他设备访问（手机、平板、其他电脑）
Section titled “子情况 2b：从局域网中的其他设备访问（手机、平板、其他电脑）”这是最麻烦的情况。流量路径为：局域网设备 → Windows 宿主机 → WSL 虚拟机，你必须设置两个跳转：
- 在 WSL 内部绑定所有接口：监听
127.0.0.1的进程永远无法从虚拟机外部访问。请使用0.0.0.0。 - 设置 Windows → WSL 虚拟机的端口转发：
- 在 镜像模式 下，这是自动完成的。
- 在 NAT 模式 下，你需要手动按端口进行设置。在管理员模式的 PowerShell 中运行：
# 获取 WSL 虚拟机的当前 IP（在 NAT 模式下，每次 WSL 重启该 IP 都会变动）$wslIp = (wsl hostname -I).Trim().Split(' ')[0]
# 将 Windows 端口 8080 转发至 WSL:8080netsh 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 进行移除。
- **让局域网设备指向
http://<windows-lan-ip>:8080**。
由于在 NAT 模式下，每次重启后 WSL 虚拟机的 IP 都会发生偏移，因此临时规则在执行 wsl --shutdown 后就会失效。对于任何需要持久化访问的需求，要么使用镜像模式，要么将端口代理步骤放入 Windows 登录时运行的脚本中。
对于来自云消息提供商（如 Telegram setWebhook、Slack events 等）的 Webhook，不要尝试死磕端口转发 —— 请使用 cloudflared 隧道。参见 Webhooks 指南。
在 Windows 上长期运行 Hermes 服务
Section titled “在 Windows 上长期运行 Hermes 服务”Hermes 工具网关 和 API 服务器属于长效运行进程。在 WSL2 中，你可以通过以下几种方式保持它们持续运行。
在 WSL 内部使用 systemd（推荐）
Section titled “在 WSL 内部使用 systemd（推荐）”如果你按照上文设置部分启用了 systemd，那么 hermes gateway 和 API 服务器的工作方式与在任何 Linux 机器上完全一致。请使用网关设置向导：
hermes gateway setup向导会提示安装 systemd 用户单元（user unit），以便在 WSL 启动时自动运行网关。
让 WSL 本身在 Windows 登录时启动
Section titled “让 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 穿透（本地模型）
Section titled “GPU 穿透（本地模型）”自 WSL 内核 5.10.43+ 起，WSL2 原生支持 NVIDIA GPU —— 仅需在 Windows 上安装标准 NVIDIA 驱动（切勿在 WSL 内部安装 Linux 版 NVIDIA 驱动），WSL 内部的 nvidia-smi 即可识别 GPU。之后，CUDA 工具包、torch、vllm、sglang 和 llama-server 就可以像往常一样针对真实 GPU 进行构建。
AMD ROCm 和 Intel Arc 在 WSL2 内部的支持仍处于发展阶段，且不在 Hermes 的测试矩阵内 —— 配合当前驱动可能有效，但我们尚无推荐的配置方案。
如果你正在运行 Windows 原生 的本地模型服务器（如 Ollama for Windows, LM Studio），且它们已经通过 Windows 驱动使用了你的 GPU，那么你根本不需要 WSL GPU 穿透 —— 只需按照上文的 “情况 1”，通过网络从 WSL 访问它们即可。
- 访问 Windows 宿主机的 Ollama / LM Studio 时提示 “Connection refused”：请参阅 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 paths are not supported” 警告：Hermes 的当前工作目录位于 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，然后将1.1.1.1或你 VPN 的 DNS 写入/etc/resolv.conf）。 - **运行安装程序后找不到
hermes**：安装程序通过~/.bashrc将~/.local/bin添加到你的 Shell PATH。你需要执行source ~/.bashrc（或打开新终端）才能在当前会话中生效。 - Windows Defender 在 WSL 文件上运行缓慢：从 Windows 访问时，Defender 会通过 9P 桥接扫描文件，这会放大跨边界访问的缓慢感。如果你只在 WSL 内部触碰 WSL 文件，这无关紧要。如果你经常针对
\\wsl$\...使用 Windows 工具，可以考虑将 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 暴露给局域网其他设备的长效服务。