Hermes Agent 在 Windows 上安裝（WSL2 完整指南）

為什麼 Windows 不能直接裝

你可能想問：Hermes 不就是 Python + Node 嗎？Windows 也能跑 Python。為什麼必須 WSL2？

• Hermes 大量使用 Unix 風格路徑（~/.hermes、/usr/local/bin）。Windows 路徑用反斜槓，轉義在 Python subprocess 呼叫裡很容易踩坑。
• Hermes 的 Skills 大部分用 Bash / sh 寫底層呼叫（git、ripgrep、fd 等命令），Windows cmd / PowerShell 不相容。
• Terminal ANSI 色彩 + 進度條在 Windows Terminal 上雖然能渲染，但 Hermes 用的 readline 庫在原生 Windows 上經常斷裂。
• 一句話：理論上能跑，實踐上 60% 的常用 Skill 都會出現奇怪問題。WSL2 讓你拿到一個乾淨的 Linux 環境，體驗和 Mac / Linux 同學完全一致。

WSL2 不是虛擬機器——它是 Windows 核心裡的輕量 Linux 子系統，啟動 1 秒，檔案系統和 Windows 互通。裝一次受用全程。

安裝 WSL2（Win10 / Win11）

以管理員身份開啟 PowerShell（Win+X 選 Terminal (Admin)），跑下面這條。

wsl --install -d Ubuntu-22.04

1. 1. 重啟電腦

   命令跑完後系統會提示重啟。重啟完成後會自動彈出 Ubuntu 終端視窗，第一次啟動會讓你設定 Linux 使用者名稱和密碼（和 Windows 賬戶無關，自己起一個就行）。

2. 2. 驗證 WSL2

   在 PowerShell 裡跑 wsl -l -v，應該看到 Ubuntu-22.04 狀態是 Running，VERSION 是 2。如果是 1，跑 wsl --set-version Ubuntu-22.04 2 升級。

3. 3. 更新系統

   在 Ubuntu 終端裡跑 sudo apt update && sudo apt upgrade -y。裝完用 sudo apt install -y curl git build-essential 裝好基礎工具。

到這一步你已經有了一個完整的 Linux 環境。Hermes 安裝步驟和 Mac / Linux 使用者完全一樣。

在 WSL Ubuntu 中安裝 Hermes

回到 Ubuntu 終端（開始選單搜 Ubuntu 或在 PowerShell 裡跑 wsl 進入），跑官方一行指令。

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

• 裝完位置：~/.hermes（這是 WSL Ubuntu 裡的 home，對應 Windows 的 \\wsl$\Ubuntu-22.04\home\<user>\.hermes）
• 裝完關閉終端再開一次讓 PATH 生效，或 source ~/.bashrc
• 驗證：hermes --version 應該輸出版本號
• 裝完跑 hermes doctor 一鍵自檢 12 項

配置 LLM Provider、裝 Skills 等步驟都在 /install 主指南里。

VS Code WSL 開發體驗

推薦配置：Windows 端裝 VS Code，透過 Remote-WSL 擴充套件連進 WSL 幹活。這樣你保留 Windows 的圖形介面，但所有終端 + 檔案操作都在 Linux 裡。

1. 1. Windows 端裝 VS Code

   從 https://code.visualstudio.com/ 下載安裝。安裝時勾選"Add to PATH"。

2. 2. 裝 Remote - WSL 擴充套件

   VS Code 裡 Ctrl+Shift+X 開啟擴充套件面板，搜 "Remote - WSL"（微軟官方），點 Install。

3. 3. 從 WSL 終端開啟專案

   在 WSL Ubuntu 終端裡 cd 到你的專案目錄，然後跑 code .。VS Code 會自動連進 WSL 開啟當前目錄，左下角會顯示綠色的 "WSL: Ubuntu"。

4. 4. 終端共用 WSL

   VS Code 內嵌終端預設就是 WSL Bash，跑 hermes 命令直接在那裡跑就行。Hermes 的輸出在 VS Code 終端裡能正常顯示彩色和進度條。

網路代理設定（必看）

中國大陸使用者大機率需要配代理才能裝 Skills（GitHub raw + 部分 LLM Provider 域名）。WSL2 預設不繼承 Windows 的代理設定，需要手動配。

• 前提：Windows 端有 Clash / V2Ray / Surge 在跑，埠比如 7890
• 獲取 WSL 看到的 Windows 主機 IP：在 WSL 裡跑 cat /etc/resolv.conf 看 nameserver 那一行
• 在 ~/.bashrc 末尾加：export HTTPS_PROXY="http://<上面那個IP>:7890"，HTTP_PROXY 同理
• 儲存後 source ~/.bashrc 立即生效
• 驗證：curl -I https://www.google.com 應該返回 200，不再卡死

配好代理後再跑 hermes skills sync 拉取 Skills registry。如果不想全域性走代理，可以只在 Hermes 配置檔案裡給 skills.proxy 單獨設一個。

WSL 常見報錯 8 種

WSL2 + Hermes 安裝路上幾乎所有人都會撞到下面 8 個錯誤之一。挨個對照即可。

• WslRegisterDistribution failed with error: 0x800701bc

  原因 / Cause: WSL2 核心未安裝或版本太舊。

  修复 / Fix: 在 PowerShell 裡跑 wsl --update。仍報錯就去微軟官網下載 WSL2 Linux 核心更新包手動裝一次。

• wsl --install 提示找不到命令

  原因 / Cause: Win10 版本低於 21H2，wsl --install 是 21H2 加的簡化命令。

  修复 / Fix: 走老流程：在 "啟用或關閉 Windows 功能" 裡勾選 Hyper-V、虛擬機器平臺、適用於 Linux 的 Windows 子系統，重啟後到 Microsoft Store 裝 Ubuntu。

• WSL Ubuntu 啟動後卡死在 "Installing, this may take a few minutes"

  原因 / Cause: 系統盤空間不足或 Hyper-V 沒啟用。

  修复 / Fix: 檢查 C 盤剩餘空間需要 ≥ 5 GB。Hyper-V 在 BIOS 裡要開啟 VT-x（Intel）或 SVM（AMD）。

• curl install 命令在 WSL 裡卡在 "Installing Python deps"

  原因 / Cause: WSL2 預設 DNS 用 Windows 主機解析，國內訪問 pypi.org 偶爾抽風。

  修复 / Fix: 在 WSL Ubuntu 裡：echo "[network]\ngenerateResolvConf = false" | sudo tee /etc/wsl.conf；然後 PowerShell 裡 wsl --shutdown 重啟 WSL；再手動 sudo nano /etc/resolv.conf 寫 nameserver 8.8.8.8。

• hermes 命令在 VS Code 終端裡能跑，在 Windows Terminal 裡報 not found

  原因 / Cause: Windows Terminal 預設 profile 不是 WSL。

  修复 / Fix: Windows Terminal 裡 Ctrl+, 開啟設定，把 Default profile 設成 Ubuntu-22.04。

• WSL 檔案系統訪問 Windows 端 D:\ 專案特別慢

  原因 / Cause: WSL 跨盤訪問（/mnt/d/...）走的是 9P 協議，比 ext4 慢 10 倍以上。

  修复 / Fix: 把專案從 Windows D 盤移到 WSL 自己的 ~/projects 下面（在 WSL home 下）。需要 Windows 端訪問就走 \\wsl$\Ubuntu-22.04\home\<user>\projects。

• hermes 啟動報 ANSI 色彩在 Windows Terminal 裡亂碼

  原因 / Cause: Windows Terminal 字型不支援 Powerline / Nerd Font。

  修复 / Fix: 裝一個 Nerd Font 字型（推薦 JetBrainsMono Nerd Font）然後在 Windows Terminal 設定裡把 Ubuntu profile 的字型改成它。

• WSL2 記憶體佔用持續增長不釋放

  原因 / Cause: WSL2 預設不會主動歸還記憶體給 Windows。

  修复 / Fix: 在 Windows 使用者目錄建 .wslconfig 檔案，寫：[wsl2]\nmemory=4GB\nswap=2GB；儲存後 wsl --shutdown 重啟 WSL 即可生效。