The Hermes Bible — 繁體中文版

Section: Using Hermes · URL: https://hermesbible.com/docs/user-guide/windows-wsl-quickstart

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 之間來回傳輸檔案、雙向網路設定，以及人們實際會遇到的坑。

INFO — 簡體中文

本頁面維護了一份中文的最小安裝路徑說明——可透過右上角的 language 選單切換至簡體中文。

為什麼選 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 sockets、訊號語義、支援 PTY 的終端機、bash/zsh 等 shell，以及 rg、git、ffmpeg 等在 Linux 上如常運作的工具。

WSL2 的實際影響：

Hermes CLI、閘道器、sessions、記憶體、技能和工具運行時都在 Linux 虛擬機內部。
Windows 程式（瀏覽器、原生應用程式、使用你已登入設定檔的 Chrome）在外部。
每次你想讓兩者溝通——共享檔案、開啟 URL、控制 Chrome、連線到本地模型伺服器、將 Hermes 閘道器暴露給你的手機——你都需要穿越邊界。這些邊界正是本指南的主題。

安裝 WSL2

從管理員 PowerShell 或 Windows Terminal 執行：

wsl --install

在全新的 Windows 10 22H2+ 或 Windows 11 上，這會安裝 WSL2 核心、Virtual Machine Platform 功能和預設的 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://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 repos — Linux 側（~/code/...、~/projects/...）。
你的模型、資料集、venvs — Linux 側。

遵循此規則的好處：

快速 I/O。 在 /mnt/c/... 上的操作經過 9P，比原生 ext4 慢 10–100 倍。在 ~/code 下感覺瞬間完成的萬檔 repo 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     # 只需一次——提供 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

如果你用 Windows 編輯器在 Windows 側編輯檔案，它們可能會加上 CRLF 換行符號。當 Linux 側的 bash 或 Python 讀取這些檔案時，shell 腳本會出現 bad interpreter: /bin/bash^M 錯誤，Python 也可能在處理帶有 BOM 的 .env 檔案時失敗。

修復方法是在 WSL 內（而非 Windows 上）設定合理的 git config：

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

對於已有 CRLF 的檔案：

sudo apt install dos2unix
dos2unix path/to/script.sh

「要 clone 到 WSL 內部還是 `/mnt/c`？」

Clone 到 WSL 內部。永遠如此，除非你有特定理由不這麼做。典型的 Hermes 工作流程（hermes chat、使用 rg/ripgrep 搜尋 repo 的工具呼叫、檔案監聽器、背景閘道器）在 ~/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 在具有獨立網路堆疊的輕量級虛擬機中運行。這意味著 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：從區域網路上的其他裝置（手機、平板、另一台電腦）

這才是真正的痛點。流量流動方向是區域網路裝置 → Windows 主機 → WSL 虛擬機，你必須設定兩段跳躍：

在 WSL 內綁定所有介面。 監聽 127.0.0.1 的進程永遠無法從虛擬機外部訪問。使用 0.0.0.0。

埠轉發 Windows → WSL 虛擬機。 在鏡像模式下這是自動的。在 NAT 模式下你必須手動設定，逐個連接埠，在管理員 PowerShell 中執行：

# 取得 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

之後可用 netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080 移除。

將區域網路裝置指向 http://<windows-lan-ip>:8080。

由於 NAT 模式下 WSL 虛擬機 IP 在每次重啟時都會變化，一次性規則只在下次 wsl --shutdown 前有效。要持久化，請使用鏡像模式，或將埠代理步驟放在 Windows 登入時執行的腳本中。

對於來自雲端訊息供應商的 webhook（Telegram setWebhook、Slack events 等），不要與埠轉發搏鬥——使用 cloudflared 隧道。參閱 webhooks 指南。

在 Windows 上長期運行 Hermes 服務

Hermes 工具閘道器和 API 伺服器是長運行的進程。在 WSL2 中有幾種保持它們運行的方式。

桌面捷徑快速開啟 Hermes

如果你只是想要一個雙擊啟動的互動式 Hermes shell，可以在 Windows 側建立捷徑，讓它自動跳入 WSL：

在 Windows 桌面上按右鍵，選擇新增 -> 捷徑。

目標輸入你的發行版名稱（如需要請替換 Ubuntu）：

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

將它命名為顯而易見的名稱，如 Hermes。

這會開啟 Windows Terminal，啟動你的 WSL 發行版，將你放在 Linux 主目錄中，然後啟動 Hermes。如果 hermes 尚未在 PATH 中，先手動開啟 WSL 並執行 source ~/.bashrc，或將命令替換為在你的專案目錄中執行 uv run hermes。

可選的美化：

自訂圖示： 開啟屬性 -> 變更圖示，指向一個 .ico 檔案，例如 repo 中的 Hermes favicon。
釘選啟動器： 捷徑正常運作後，將它釘選到開始選單或工作列，這樣就不用再去找它了。

在 WSL 內使用 systemd（建議）

如果你按照上方安裝步驟啟用了 systemd，hermes gateway 和 API 伺服器的運作方式與在任何 Linux 機器上相同。使用閘道器設定精靈：

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 建構。

AMD ROCm 和 Intel Arc 在 WSL2 內的支援仍在發展中，不在 Hermes 的測試矩陣內——在目前的驅動程式下可能可以運作，但我們沒有可以推薦的配方。

如果你運行的是Windows 原生的本地模型伺服器（Windows 版 Ollama、LM Studio），它已經透過 Windows 驅動程式使用你的 GPU，你完全不需要 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），或是缺少防火牆規則。

在 repo 中執行 git status / hermes chat 極度緩慢。 你可能在 /mnt/c/... 下操作。將 repo 移到 ~/code/...（Linux 側）。速度提升一個數量級。

腳本出現 bad interpreter: /bin/bash^M。 Windows 編輯器產生的 CRLF 換行符號。執行 dos2unix script.sh，並在你的 WSL git config 中設定 core.autocrlf input。

透過 MCP 啟動的 Windows 二進位檔出現「UNC paths are not supported」警告。 Hermes 的工作目錄在 Linux 檔案系統內，Windows cmd.exe 不知道該怎麼處理。從 /mnt/c/... 啟動 Hermes（該 session），或使用一個在呼叫 Windows 可執行檔之前先 cd 到 Windows 可達路徑的包裝器。

從睡眠/休眠恢復後時鐘偏移。 WSL2 的時鐘在主機從睡眠恢復後可能落後數分鐘，這會破壞任何基於憑證的功能（OAuth、HTTPS API）。按需修復：

sudo hwclock -s

或安裝 ntpdate 並在登入時執行。

啟用鏡像模式後或連接 VPN 時 DNS 停止運作。 鏡像模式將主機網路設定代理到 WSL——如果 Windows DNS 有問題（VPN 分割通道、企業 DNS），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（或開啟新終端機）才能在當前 session 中生效。

Windows Defender 在 WSL 檔案上運行緩慢。 Defender 透過 9P 橋接掃描從 Windows 訪問的檔案，這放大了 /mnt/c 式跨邊界存取的慢速問題。如果你只從 WSL 內部操作 WSL 檔案，這不影響你。如果你經常使用 Windows 工具操作 \\wsl$\...，考慮將 WSL 發行版路徑從即時掃描中排除。

磁碟空間不足。 WSL2 將其 VM 磁碟以稀疏 VHDX 格式儲存在 %LOCALAPPDATA%\Packages\...。它會增長但不會在刪除檔案後自動縮小。要回收空間：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 暴露給網路其他部分的長運行服務。