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 暴露給網絡其餘部分的長期運行服務。