<!-- Source: https://hermesbible.com/docs/user-guide/windows-native -->

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

Hermes 可以在 Windows 10 和 Windows 11 上原生運作 —— 不需要 WSL、不需要 Cygwin、不需要 Docker。本頁將深入說明：哪些功能可原生運作、哪些只能在 WSL 中使用、安裝程式實際做了什麼，以及你可能需要調整的 Windows 特定設定。

如果你只想安裝，首頁 或安裝頁面 上的一行指令就夠了。遇到問題時再回來這裡。

提示 — 想用 WSL 嗎？

如果你偏好真正的 POSIX 環境（用於 Dashboard 的內建終端、fork 語義、Linux 風格的檔案監聽器等），請參閱 Windows（WSL2）指南。兩者可以共存：原生資料存放在 %LOCALAPPDATA%\hermes，WSL 資料存放在 ~/.hermes。

快速安裝

開啟 PowerShell（或 Windows Terminal）並執行：

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

不需要管理員權限。安裝程式會安裝到 %LOCALAPPDATA%\hermes\ 並將 hermes 加入你的 使用者 PATH —— 安裝完成後請開啟新的終端。

安裝程式選項（需要使用 scriptblock 形式來傳遞參數）：

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1))) -NoVenv -SkipSetup -Branch main

安裝程式會自動重試不穩定的 git fetch，並移除任何下載的 install.ps1 檔案中的 BOM，因此在 HTTP 傳輸過程中取得的 UTF-8 BOM 不會再破壞 [scriptblock]::Create((irm ...)) 形式。

桌面安裝程式（替代方案）

也提供了一個精簡的 GUI 安裝程式 —— 如果你偏好雙擊 .exe 而不是開啟 PowerShell，這會很方便。下載 Hermes Desktop，執行安裝程式，首次啟動時 GUI 會在底層呼叫 install.ps1 來配置 Python（透過 uv）、Node、PortableGit 以及下文所述的其他依賴項。首次執行後，桌面應用程式和透過 PowerShell 安裝的 hermes CLI 共享相同的 %LOCALAPPDATA%\hermes\hermes-agent 安裝目錄和 %LOCALAPPDATA%\hermes 資料目錄 —— 你可以在 GUI 和 CLI 之間自由切換。

當你想要熟悉的 Windows 安裝體驗，或是要把 Hermes 交給非開發者使用時，請使用桌面安裝程式；當你已經在終端中時，請使用 PowerShell 一行指令。

依賴項自動安裝（dep_ensure）

首次啟動時（以及偵測到缺少工具時按需執行），Hermes 會執行一個小型 Python 引導程式 —— hermes_cli/dep_ensure.py —— 來檢查並延遲安裝所需的非 Python 依賴項。在 Windows 上，相關的依賴項如下：

每個依賴項都有類似 shutil.which(...) 的檢查；如果缺少某個二進位檔且執行環境是互動式的，dep_ensure 會提供安裝選項（實際安裝邏輯委派給 scripts\install.ps1 -ensure <dep>）。非互動式執行（gateway、cron、headless 桌面啟動）會跳過提示，並顯示明確的 this feature needs <dep> 錯誤。

安裝程式實際做了什麼

從頭到尾，依序如下：

1. 引導安裝 uv —— Astral 的快速 Python 管理器。安裝到 %USERPROFILE%\.local\bin。
2. 透過 uv 安裝 Python 3.11。不需要已有的 Python。
3. 安裝 Node.js 22（有 winget 就用 winget，否則下載 portable Node tarball 解壓到 %LOCALAPPDATA%\hermes\node）。用於瀏覽器工具和 WhatsApp bridge。
4. 安裝 portable Git —— 如果 git 已在 PATH 上，安裝程式會直接使用；否則下載精簡、自包含的 PortableGit（約 45 MB，來自官方 git-for-windows 發佈版）到 %LOCALAPPDATA%\hermes\git。不需要管理員、不會寫入 Windows 安裝程式登錄檔、不會干擾系統上的其他軟體。
5. 複製 repo 到 %LOCALAPPDATA%\hermes\hermes-agent 並在其中建立 virtualenv。
6. 分層 uv pip install —— 先嘗試 .[all]，如果 git+https 依賴項在受到速率限制的 GitHub 上不穩定，會依序退回較小的套件組（[messaging,dashboard,ext] → [messaging] → .）。避免了「單一依賴項不穩定就退回最精簡安裝」的失敗模式。
7. 根據 .env 自動安裝通訊 SDK —— 如果存在 TELEGRAM_BOT_TOKEN / DISCORD_BOT_TOKEN / SLACK_BOT_TOKEN / SLACK_APP_TOKEN / WHATSAPP_ENABLED，會執行 python -m ensurepip --upgrade 和針對性的 pip install，確保各平台的 SDK 可以正常匯入。
8. 設定 HERMES_GIT_BASH_PATH 為解析到的 bash.exe，讓 Hermes 在新的 shell 中能確定性地找到它。
9. 將 %LOCALAPPDATA%\hermes\hermes-agent\venv\Scripts 加入使用者 PATH 並設定 HERMES_HOME=%LOCALAPPDATA%\hermes —— 在你開啟新終端後即可使用 hermes 命令（並指向你的資料目錄）。
10. 執行 hermes setup —— 正常的首次執行精靈（模型、供應商、工具組）。可用 -SkipSetup 跳過。

提示 — 在 Windows 上跳過供應商設定

在 Windows 上，設定各工具的 API 金鑰（Firecrawl、FAL、Browser Use、OpenAI TTS）是讓 agent 正常運作時摩擦最大的部分。Nous Portal 訂閱可以透過單一 OAuth 登入涵蓋模型和所有這些工具。安裝程式完成後，執行 hermes setup --portal 即可一次設定完成。

功能對照表

除了 Dashboard 的內建終端分頁外，所有功能都能在 Windows 上原生運作。

Dashboard 的 /chat 分頁透過 POSIX PTY（ptyprocess）嵌入了真正的終端。原生 Windows 沒有等效的原始介面；Python 的 pywinpty / Windows ConPTY 可以實現，但需要另外開發 —— 視為未來的工作。其餘的 Dashboard 功能都能原生運作 —— 只有那個分頁會顯示「請使用 WSL2」的橫幅。

Hermes 如何在 Windows 上執行 shell 命令

Hermes 的終端工具透過 Git Bash 執行命令，與 Claude Code 使用相同的策略。這樣就不用改寫每個工具就能繞過 POSIX 與 Windows 之間的差異。

bash.exe 的解析順序：

1. 若已設定 HERMES_GIT_BASH_PATH 環境變數，則使用該路徑。
2. %LOCALAPPDATA%\hermes\git\usr\bin\bash.exe（安裝程式管理的 PortableGit）。
3. %LOCALAPPDATA%\hermes\git\bin\bash.exe（舊版 Git-for-Windows 結構）。
4. 系統級 Git-for-Windows 安裝（%ProgramFiles%\Git\bin\bash.exe 等）。
5. MSYS2、Cygwin 或 PATH 上的任何 bash.exe（最後手段）。

安裝程式會明確設定 HERMES_GIT_BASH_PATH，這樣新的 PowerShell session 就不用重新探索。如果你希望 Hermes 使用特定的 bash —— 例如系統的 Git Bash 或透過符號連結指向 WSL 的 bash —— 可以覆蓋此設定。

注意事項： MinGit 的目錄結構與完整版 Git-for-Windows 安裝程式不同 —— bash 位於 usr\bin\bash.exe，而不是 bin\bash.exe。Hermes 兩個路徑都會檢查。如果你要手動解壓 MinGit zip，請確保選擇 非 busybox 版本（MinGit-*-64-bit.zip，而非 MinGit-*-busybox*.zip）—— busybox 版本提供的是 ash 而非 bash，且大部分核心工具都缺失。

Windows 上的 UTF-8 主控台

Python 在 Windows 上的預設 stdio 使用主控台的活動代碼頁（通常是 cp1252 或 cp437）。Hermes 的橫幅、斜線命令清單、工具資訊、Rich 面板和技能描述都包含 Unicode。如果不加處理，任何這些內容都會因 UnicodeEncodeError: 'charmap' codec can't encode character… 而崩潰。

修正在 hermes_cli/stdio.py::configure_windows_stdio() 中，會在每個進入點的早期階段呼叫（cli.py::main、hermes_cli/main.py::main、gateway/run.py::main）。它會：

1. 透過 kernel32.SetConsoleCP / SetConsoleOutputCP 將主控台代碼頁切換到 CP_UTF8（65001）。
2. 使用 errors='replace' 將 sys.stdout / sys.stderr / sys.stdin 重新設定為 UTF-8。
3. 設定 PYTHONIOENCODING=utf-8 和 PYTHONUTF8=1（透過 setdefault，因此使用者明確設定的值優先），讓子 Python process 繼承 UTF-8。
4. 如果 EDITOR 和 VISUAL 都未設定，則設定 EDITOR=notepad（請參閱下方的編輯器章節）。

具有冪等性。在非 Windows 系統上不會執行任何操作。

選擇退出： 在環境中設定 HERMES_DISABLE_WINDOWS_UTF8=1 可退回使用舊版 cp1252 stdio 路徑。適用於排除編碼錯誤；在正常情況下不太可能是正確的設定。

編輯器（Ctrl-X Ctrl-E、/edit）

在 #21561 之前，按下 Ctrl-X Ctrl-E 或輸入 /edit 在 Windows 上會默默地不做任何事。prompt_toolkit 有一個硬編碼的 POSIX 絕對路徑退回清單（/usr/bin/nano、/usr/bin/pico、/usr/bin/vi、……），在 Windows 上永遠無法解析 —— 即使安裝了完整的 Git for Windows 也不行。

Hermes 的 Windows stdio 墊片現在將 EDITOR=notepad 設為預設值。Notepad 隨每台 Windows 電腦附帶，可作為阻塞式編輯器使用 —— subprocess.call(["notepad", file]) 會阻塞直到視窗關閉。

使用者覆蓋仍然優先（它們在 setdefault 之前檢查）：

VS Code 的 --wait 標記至關重要 —— 沒有它的話，編輯器會立即返回，Hermes 拿到的會是空白緩衝區。

在你的 PowerShell 設定檔中永久設定：

# 在 $PROFILE 中
$env:EDITOR = "code --wait"

或在系統設定 → 環境變數中設定為使用者環境變數，讓每個新 shell 都能使用。

在 CLI 中使用 Ctrl+Enter 換行

Windows Terminal 會將 Ctrl+Enter 作為專用按鍵序列傳遞。Hermes 將其綁定為「插入換行」，這樣你就可以在 CLI 中編寫多行提示，而不需要退回使用 Esc 再 Enter。在 Windows Terminal、VS Code 整合終端以及任何支援 VT 轉義序列的現代 Windows 主控台主機中都能運作。

在舊版 cmd.exe 主控台中，Ctrl+Enter 會退化為普通的 Enter —— 請改用 Esc Enter，或升級到 Windows Terminal（它是免費的，且在 Windows 11 上已預設安裝）。

在 Windows 登入時執行 gateway

在 Windows 上，hermes gateway install 使用排程作業並有啟動資料夾作為退回方案 —— 不需要管理員權限。

安裝

hermes gateway install

底層實際執行的操作：

1. schtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway —— 註冊一個在你登入時以標準（非提升）權限執行的作業。不會出現 UAC 提示。
2. 如果 schtasks 被群組原則封鎖，會退回在 %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup 中寫入一個 start /min cmd.exe /d /c <wrapper> 快捷方式。效果相同，只是稍微粗糙一些。
3. 透過 pythonw.exe 分離啟動 gateway —— 不是 python.exe。pythonw.exe 沒有附加主控台，因此不受來自同級 process 的 CTRL_C_EVENT 廣播影響（這是一個真實的問題，過去曾在同一 process 群組中按 Ctrl+C 時意外終止 gateway）。

啟動時使用的標記：DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW | CREATE_BREAKAWAY_FROM_JOB。

管理

hermes gateway status      # 合併檢視：schtasks + Startup 資料夾 + 執行中的 PID
hermes gateway start       # 立即啟動排程作業
hermes gateway stop        # 優雅的 SIGTERM 等效（透過 psutil 的 TerminateProcess）
hermes gateway restart
hermes gateway uninstall   # 移除 schtasks 項目、Startup 快捷方式、pid 檔案

hermes gateway status 是冪等的 —— 呼叫一千次也不會意外終止 gateway。（在 PR #21561 之前它會默默地終止，因為 os.kill(pid, 0) 在 C 層級與 CTRL_C_EVENT 衝突 —— 如果你有興趣了解細節，請參閱下方的「進程管理內部機制」。）

為什麼不用 Windows 服務？

安裝服務需要管理員權限，且將 gateway 的生命週期綁定到機器啟動，而非使用者登入。典型的 Hermes 使用者希望的是：登入 → gateway 可用，登出 → gateway 結束。排程作業正好能做到這一點，且不需要提升權限。如果你真的想要服務，可以使用 nssm 或手動執行 sc create —— 但你大概不需要。

資料結構

在原生 Windows 上，安裝程式設定 HERMES_HOME=%LOCALAPPDATA%\hermes，因此你的資料和可捨棄的安裝都位於同一個 %LOCALAPPDATA%\hermes 根目錄下：安裝/執行環境是 hermes-agent\、git\、node\ 和 bin\ 子目錄，而你的資料檔案直接存放在 %LOCALAPPDATA%\hermes 中。重新安裝只會替換 hermes-agent\ 簽出，所以你的資料會保留 —— 但因為兩者共享根目錄，如果你想保留資料，不要執行 Remove-Item -Recurse %LOCALAPPDATA%\hermes；請改為刪除 hermes-agent\ 子目錄。你的資料目錄與 Linux 的 ~/.hermes 結構相同，因此可以在機器之間同步。

覆蓋 HERMES_HOME： 將環境變數設定為指向不同的資料目錄（例如 %USERPROFILE%\.hermes 以匹配 Linux/WSL 結構）。與 Linux 上的使用方式相同。

瀏覽器工具

瀏覽器工具使用 agent-browser（一個 Node 輔助工具）來驅動 Chromium。在 Windows 上：

• 安裝程式透過 npm 將 agent-browser 加入 PATH。
• shutil.which("agent-browser", path=...) 會自動找到 .cmd 墊片 —— CreateProcessW 無法執行沒有副檔名的 shebang 檔案，因此 Hermes 總是解析為 .CMD 包裝器。不要手動執行 shebang 檔案；務必透過 .cmd 執行。
• Playwright Chromium 在首次執行時自動安裝（npx playwright install chromium）。如果安裝失敗，hermes doctor 會顯示問題並提供修復提示。

在 Windows 上執行 Hermes — 實用注意事項

安裝後的 PATH

安裝程式透過 [Environment]::SetEnvironmentVariable 將 %LOCALAPPDATA%\hermes\hermes-agent\venv\Scripts 加入你的使用者 PATH。現有的終端不會立即生效 —— 安裝後請開啟新的 PowerShell 視窗（或 Windows Terminal 分頁）。關閉後重新開啟，不要手動執行 $env:PATH += …，除非你清楚自己在做什麼。

驗證方式：

Get-Command hermes        # 應該輸出 C:\Users\<you>\AppData\Local\hermes\hermes-agent\venv\Scripts\hermes.exe
hermes --version

環境變數

Hermes 同時支援 $env:X（process 範圍）和使用者環境變數（永久，在系統設定 → 環境變數中設定）。將 API 金鑰設定在 %LOCALAPPDATA%\hermes\.env（你的 HERMES_HOME）是正常的做法 —— 與 Linux 相同：

OPENROUTER_API_KEY=sk-or-...
TELEGRAM_BOT_TOKEN=...

不要將密鑰放在使用者環境變數中，除非你特別希望每個 Windows process 都能看到它們（通常不是你想要的）。

Windows 特定的環境變數

以下僅影響原生 Windows 安裝：

解除安裝

在 PowerShell 中執行：

hermes uninstall

這是乾淨的解除安裝路徑 —— 移除 schtasks 項目、Startup 資料夾快捷方式、hermes.cmd 墊片、刪除 %LOCALAPPDATA%\hermes\hermes-agent\，並從使用者 PATH 中移除。它會保留 %LOCALAPPDATA%\hermes\ 的其他內容（你的 config、auth、skills、sessions、logs），以防你要重新安裝。

要徹底清除：

hermes uninstall
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes"
# 如果你曾經使用過舊版 CLI/WSL 資料目錄，也一併移除：
Remove-Item -Recurse -Force "$env:USERPROFILE\.hermes"

hermes uninstall CLI 子命令也會處理 schtasks 項目是以不同任務名稱註冊的情況（較舊的安裝）—— 它是透過安裝路徑而非硬編碼的任務名稱來搜尋。

進程管理內部機制

這是背景材料 —— 除非你在調試「它自己殺自己」的怪異問題，否則可以跳過。

在 Linux 和 macOS 上，POSIX 慣用法 os.kill(pid, 0) 是一個無操作的權限檢查：「這個 PID 還活著嗎？我能發送訊號嗎？」在 Windows 上，Python 的 os.kill 將 sig=0 映射為 CTRL_C_EVENT —— 它們在整數值 0 上衝突 —— 並透過 GenerateConsoleCtrlEvent(0, pid) 路由，這會將 Ctrl+C 廣播給包含目標 PID 的整個主控台 process 群組。這是 bpo-14484，自 2012 年開啟至今。它不會被修復，因為改變會破壞依賴當前行為的腳本。

後果：在 Windows 上任何透過 os.kill(pid, 0) 來「檢查此 PID 是否活著」的代碼路徑都會默默地終止目標。Hermes 已將所有這類位置（11 個檔案中的 14 處）遷移到 gateway.status._pid_exists()，它使用 psutil.pid_exists()（在 Windows 上透過 OpenProcess + GetExitCodeProcess 實現 —— 不使用訊號）。如果你正在編寫插件或補丁，請直接使用 psutil.pid_exists() 或 gateway.status._pid_exists() —— 絕對不要使用 os.kill(pid, 0)。

scripts/check-windows-footguns.py 在 CI 中強制執行此規則：任何新的 os.kill(pid, 0) 呼叫都會導致 Windows footguns (blocking) 檢查失敗，除非該行帶有 # windows-footgun: ok — <reason> 標記。

常見問題

安裝後立即出現 hermes: command not found。 請開啟新的 PowerShell 視窗。安裝程式已將 %LOCALAPPDATA%\hermes\bin 加入使用者 PATH，但現有的 shell 需要重新啟動才能生效。在此期間你可以執行 & "$env:LOCALAPPDATA\hermes\bin\hermes.cmd"。

執行工具時出現 WinError 193: %1 is not a valid Win32 application。 你觸及了一個繞過 .cmd 墊片的 shebang 檔案執行。Hermes 透過 shutil.which(cmd, path=local_bin) 來解析命令，讓 PATHEXT 能找到 .CMD —— 如果你正在透過硬編碼路徑呼叫工具，請改用 .cmd 變體（例如 npx.cmd 而不是 npx）。

[scriptblock]::Create(...) 失敗並顯示 The assignment expression is not valid。 你的 install.ps1 下載帶有 UTF-8 BOM。irm | iex 形式會自動移除 BOM；[scriptblock]::Create((irm ...)) 不會。請使用簡單的 irm | iex 形式重新執行，或手動下載腳本並透過 [IO.File]::WriteAllText($path, $text, (New-Object Text.UTF8Encoding $false)) 儲存為不含 BOM 的檔案。

Gateway 在重啟後無法保持運作。 檢查 hermes gateway status —— 它合併了 schtasks 項目、Startup 資料夾快捷方式（如果使用）和即時 PID。如果 schtasks 已註冊但未執行，群組原則可能封鎖了 ONLOGON 觸發器。執行 schtasks /Query /TN HermesGateway /V /FO LIST 來查看作業的失敗原因，或透過解除安裝並使用 HERMES_GATEWAY_FORCE_STARTUP=1 重新安裝來退回使用 Startup 資料夾路徑。

設定 $env:EDITOR 後 /edit 仍然沒有反應。 你只在目前的 process 中設定；請關閉並重新開啟 shell，或在系統設定 → 環境變數中設定為使用者範圍。在新的 PowerShell 視窗中使用 echo $env:EDITOR 驗證。

瀏覽器工具啟動了但工具逾時。 Chromium 在首次執行時自動安裝。如果安裝失敗（GitHub 速率限制、Playwright CDN 故障），請執行 hermes doctor —— 它會顯示缺少的 Chromium 並輸出確切的 npx playwright install chromium 命令來修復。

agent-browser 因奇怪的 Node 版本錯誤而失敗。 安裝程式在 %LOCALAPPDATA%\hermes\node 配置了 Node 22，但你的 PATH 上可能有一個較舊的系統 Node 18 排在前面。請將 Hermes 的 node 目錄在 PATH 中往前移動，或刪除系統安裝（如果你不在其他地方使用 Node）。

中日文或阿拉伯字元在 CLI 中顯示為 ?。 UTF-8 stdio 墊片未啟動。檢查 HERMES_DISABLE_WINDOWS_UTF8 是否未設定（Get-ChildItem env:HERMES_DISABLE_WINDOWS_UTF8）。如果它為空但仍顯示 ?，主控台主機（非常舊的 cmd.exe）可能根本不支援 UTF-8 —— 請切換到 Windows Terminal。

Gateway 無法傳送 Telegram 照片 —— 「BadRequest: payload contains invalid characters」。 這與 Windows 無關，但有時首先在 Windows 上出現。通常表示你的檔案路徑在 JSON 請求體中包含未轉義的反斜線。Telegram 應該接收的是 Hermes 正常化後的路徑，而非原始的 Windows 路徑 —— 如果你在自訂插件中看到此問題，請確保傳遞的是 Hermes 提供的路徑，而非使用者輸入的 str(Path(...))。

git pull 後出現「在我的另一台機器上可以運作」的編碼怪異問題。 如果你在 Windows 上使用非 UTF-8 編輯器（舊版 Windows 上的 Notepad、某些中文輸入法）編輯了 Hermes 設定或技能檔案，檔案可能以 BOM 儲存。Hermes 在大多數設定讀取中容忍 utf-8-sig，但折疊式 YAML 標量（description: >）中的 BOM 會默默地破壞 YAML 解析。請將檔案重新儲存為不含 BOM 的純 UTF-8。

接下來去哪裡

• 安裝 —— 完整的安裝頁面，包含 Linux/macOS/WSL2/Termux。
• Windows（WSL2）指南 —— 如果你需要 POSIX 語義或 Dashboard 終端分頁。
• CLI 參考 —— 所有 hermes 子命令。
• 常見問題 —— 常見的非 Windows 特定問題。
• 訊息閘道 —— 在 Windows 上執行 Telegram/Discord/Slack。

---

---

Windows（WSL2）指南