Windows 安裝

安裝遇到困難？

點擊加入中文社區微信群，提問並獲取群內專家幫助。

完全沒有經驗？ 強烈建議先下載 WorkBuddy（微信掃碼即用，無需任何配置），然後讓它安裝中文社區文檔 MCP 來協助你安裝 Hermes Agent。如果後續 Hermes 出現問題，也可以讓 WorkBuddy 對其進行修復，反之亦然——兩個 Agent 互為主備，這是社區推薦的最佳方案。

電腦上已經有 Agent？ 如果你已經在用龍蝦 OpenClaw 或國內版本（QClaw、AutoClaw），或者 Trae、Claude Code、Codex、Cursor、Qoder 等 Coding Agent，都可以讓它讀文檔來協助你完成安裝，你可以不用關心任何技術細節。

如何讓你的 Agent 接入中文社區文檔？

方式一（最簡單）：把中文社區網址 https://hermesagent.org.cn 發給它，讓它自己訪問並閱讀文檔。

方式二（更精準，推薦）：直接把下面這段話複製發給你的 Agent，它會自己完成配置：

請把這個 Hermes 中文文檔 MCP server 加到你的配置裡：
https://mcp.hermesagent.org.cn/v1
（Streamable HTTP，無需 API Key、無需登錄）
加完後用它幫我查 Hermes Agent 中文文檔來指導我完成安裝。

方式二配好後，Agent 就能按關鍵詞直接檢索並讀取中文社區全部文檔的全文。

其他求助途徑：也可以先詢問豆包、DeepSeek 等 AI 助手。

如果你主要在 Windows 上使用 Hermes Agent，這一頁就是給你的。重點只有一句話：Windows 和類 Linux / macOS 的安裝命令不一樣。

先回答三個問題

1. 什麼是 PowerShell？

PowerShell 是 Windows 自帶的命令行程序。你可以把它理解成：

Windows 裡的終端
一個可以輸入命令、安裝軟件、運行腳本的窗口

如果你以前聽過這些詞，它們大致是一個意思：

命令行
終端
Shell
PowerShell

對 Windows 用戶來說，你不需要先理解所有概念。你只需要知道：

後面文檔裡寫的 PowerShell 命令，就是要粘貼到 PowerShell 窗口裡執行。

2. 怎麼打開 PowerShell？

最簡單的方法：

按一下鍵盤左下角 Windows 鍵
輸入 PowerShell
點擊 Windows PowerShell 或 PowerShell

你也可能會看到：

Windows Terminal

這也可以用，但請確認打開後當前標籤頁是 PowerShell。

你應該把命令粘貼到哪裡？

請把命令粘貼到 PowerShell 窗口本身，不要粘貼到：

瀏覽器地址欄
文件資源管理器地址欄
“運行”對話框
Word / 記事本 / 聊天框

如果你不知道怎麼粘貼，可以用下面任意一種方法：

最常用：按鍵盤 Ctrl + V
如果 Ctrl + V 沒反應：在 PowerShell 窗口裡點一下鼠標右鍵，很多電腦會直接粘貼
Windows Terminal 裡通常也支持 Ctrl + Shift + V，但大多數情況下先試 Ctrl + V 就夠了

粘貼成功後，你會看到那一整行命令出現在 PowerShell 窗口裡；這時再按一下 Enter（回車鍵） 才會真正開始執行。

3. 什麼時候需要管理員 PowerShell？

安裝 WSL2：通常需要 管理員 PowerShell
直接安裝 Hermes：通常普通 PowerShell 就夠了

也就是說：

想裝 WSL2 → 可以右鍵 PowerShell，選擇“以管理員身份運行”
想直接跑 install.ps1 → 一般直接打開普通 PowerShell 即可

WSL2 到底是什麼？

WSL2 的全名是 Windows Subsystem for Linux 2。
你可以把它簡單理解成：

在 Windows 電腦裡放了一個 Linux 終端環境
你不用單獨裝雙系統，也不用自己手搓虛擬機
安裝完成後，開始菜單裡通常會多一個 Ubuntu
打開 Ubuntu 後，你看到的是 Linux 命令行

對新手來說，最重要的不是記住全名，而是記住下面這句話：

WSL2 = 讓你在 Windows 電腦上，按 Linux 的方式裝和用 Hermes。

不必須。現階段 Hermes Agent 已經對 Windows 原生安裝做了很多適配，已經可以直接在 PowerShell 中原生安裝和使用。WSL2 現在更像是一條可選路徑，適合你明確偏好 Linux / Ubuntu 終端，或者需要 POSIX 語義、Linux 文件監聽、Dashboard 內嵌終端等特定能力時使用。

如果你只是想在 Windows 本機安裝 Hermes、配置模型、運行 CLI、接入飛書或其他消息網關，可以優先使用原生 PowerShell 安裝命令。

安裝了 WSL2 之後，你實際會怎麼用？

你平時還是正常用 Windows。
只有在安裝和運行 Hermes 的時候，你改為：

打開 Ubuntu
在 Ubuntu 終端裡粘貼 Linux 安裝命令
後續也主要在 Ubuntu 終端裡運行 hermes

也就是說：

Windows 繼續是你的桌面系統
Ubuntu（WSL2）只是 Hermes 的運行終端

如果你看到文檔裡寫：

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

那麼這條命令就應該：

在 macOS 終端
或 Linux 終端
或 Windows 裡的 Ubuntu（WSL2）終端

裡執行，不要粘貼到原生 PowerShell。

先決定走哪條路徑

路徑	適合誰	推薦程度	你要運行的命令
原生 PowerShell	想在 Windows 本機直接安裝和長期使用 Hermes Agent	推薦直接安裝	在 PowerShell 裡運行 `install.ps1`
WSL2 + Ubuntu	偏好 Linux / Ubuntu 終端，或需要 POSIX 語義、Linux 工具鏈和 WSL 網絡環境	可選	在 WSL2 裡運行 `install.sh`

推薦結論

大多數 Windows 用戶：可以直接選 原生 PowerShell。現階段 Hermes Agent 已經對 Windows 原生安裝做了很多適配，已經可以原生安裝了。
偏好 Linux 工作流 / 需要 POSIX 語義：再選擇 WSL2。

中國大陸網絡環境提示

當前頁給出的安裝命令已經由 Hermes Agent 中文社區 接入 國內鏡像加速，會優先使用國內可直連的下載鏈路。

為了提高中國大陸用戶的安裝體驗，鏡像版安裝器默認精簡了部分國人不常用、或體積較大且經常受外網影響的可選功能，例如瀏覽器自動化、Chromium 下載、WhatsApp 橋接等。建議先完成核心安裝，確認 Hermes Agent 可以正常運行；之後可讓 Hermes Agent 自身補全這些能力。

如果你還需要處理 WSL 網絡、終端代理或鏡像源配置，可參考：

WSL 安裝（中文）：Windows 10/11 安裝 WSL2 指南
WSL 網絡 / autoProxy（官方）：Microsoft Learn - Accessing network applications with WSL
Python / pip 鏡像說明：清華 TUNA - PyPI 鏡像幫助
Node.js / npm 鏡像說明：清華 TUNA - NodeJS Release 鏡像幫助 / npmmirror

方案一：原生 PowerShell（推薦直接安裝）

一鍵安裝

如果你想直接在 Windows 本機安裝，請按下面步驟來：

按 Windows 鍵
輸入 PowerShell
點擊 Windows PowerShell 或 PowerShell
把下面這行命令完整複製進去
在 PowerShell 窗口裡粘貼並按回車

你要執行的命令是：

irm https://res1.hermesagent.org.cn/install.ps1 | iex

粘貼小提示

現在多數 Windows 終端都支持 Ctrl+V
如果不行，也可以直接在窗口裡 右鍵粘貼

這個安裝器會自動嘗試處理：

uv
Python 3.11
Node.js
Git
ripgrep / ffmpeg
Hermes 本體與虛擬環境

安裝完成後，關閉並重新打開 PowerShell，再運行：

hermes
hermes model

如果你重新打開 PowerShell 後輸入 hermes 能正常啟動，就說明 Windows 原生安裝已經成功了。現階段 Hermes Agent 已經對 Windows 原生安裝做了很多適配，已經可以把這條路徑作為日常使用方案。

原生 Windows 安裝後文件大致在哪裡

默認安裝目錄通常在：

%LOCALAPPDATA%\hermes

例如：

Hermes 主目錄：%LOCALAPPDATA%\hermes
倉庫目錄：%LOCALAPPDATA%\hermes\hermes-agent
虛擬環境：%LOCALAPPDATA%\hermes\hermes-agent\venv

如果 hermes 命令暫時不可用，最常見的解決方法就是：關掉當前 PowerShell 窗口，再開一個新的。

方案二：WSL2（可選）

第一步：在管理員 PowerShell 中安裝 WSL2

如果你偏好 Linux / Ubuntu 終端，或者明確需要 POSIX 語義、Linux 工具鏈和 WSL 網絡環境，可以繼續選擇 WSL2。如果你還沒裝過 WSL，建議先看這篇中文帖子：

Windows 10/11 安裝 WSL2 指南（知乎）

然後再執行：

wsl --install -d Ubuntu

執行後按提示重啟電腦。重啟完成後，打開 Ubuntu，設置 Linux 用戶名和密碼。

第二步：在 WSL2 終端裡運行 Linux 安裝命令

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

安裝完成後，重新加載 shell：

source ~/.bashrc   # 或：source ~/.zshrc
hermes

第三步：繼續配置模型

hermes model
hermes setup

如果你選擇 WSL2，後續就主要在 Ubuntu 終端裡運行 hermes。這是一條可選的 Linux 工作流，不是 Windows 用戶安裝 Hermes Agent 的前置條件。

如果你的模型跑在 Windows 主機上

例如 Ollama、LM Studio 跑在 Windows 本機，而 Hermes 跑在 WSL2 中，這時 localhost 不一定直接可用。請繼續看提供商文檔裡的 WSL2 網絡配置。

飛書接入：Windows 用戶最容易踩的坑

這一節參考並改寫自阿里雲文章《Windows 也能跑 Hermes Agent！完整安裝教程 + 飛書接入，全程避坑》。為了避免直接照抄，這裡只保留最關鍵的結論和更穩的寫法。

1. 先完成 Hermes 本體安裝，再單獨配置網關

hermes gateway setup

在渠道列表中選擇飛書，填入：

App ID
App Secret
國內版填 feishu，海外版填 lark
連接方式一般先用默認的 websocket

然後再啟動網關：

hermes gateway run -vv

2. 如果報 `lark-oapi 未安裝`

原生 Windows 下，飛書 SDK 有時沒有被裝進 Hermes 自己的虛擬環境。可以這樣補裝：

$hermesExe = (Get-Command hermes).Source
$venvPython = Join-Path (Split-Path $hermesExe -Parent) 'python.exe'
uv pip install lark-oapi --python $venvPython

如果你還缺 websockets 或 aiohttp，也可以用同樣方式補進去：

uv pip install websockets aiohttp --python $venvPython

3. 如果網關一啟動就退出，或看到 `WinError 11`

阿里雲文章裡提到，早期某些 Windows 環境下，gateway/status.py 裡的 os.kill(pid, 0) 檢查會觸發 WinError 11，導致網關異常退出。現階段 Hermes Agent 已經對 Windows 原生安裝做了很多適配，如果你仍然遇到這個舊問題，建議先升級 Hermes 並運行 hermes doctor 排查。

如果升級後仍需要臨時規避，可以按阿里雲文章中的思路，對 gateway/status.py 做臨時補丁，把 OSError 也納入異常捕獲。下面這段 PowerShell 會自動定位文件並打補丁：

$hermesExe = (Get-Command hermes).Source
$installRoot = Split-Path (Split-Path $hermesExe -Parent) -Parent
$statusPy = Join-Path $installRoot 'gateway\status.py'

$content = Get-Content $statusPy -Raw -Encoding UTF8
$content = $content.Replace(
  'except (ProcessLookupError, PermissionError):',
  'except (ProcessLookupError, PermissionError, OSError):'
)
Set-Content $statusPy $content -Encoding UTF8 -NoNewline

然後重新啟動：

$env:PYTHONUTF8 = '1'
hermes gateway run -vv

注意

這是面向舊版本或個別環境的臨時規避方案。正常情況下請優先升級 Hermes Agent，或使用 hermes doctor 自動診斷，不需要因為這個舊問題放棄 Windows 原生安裝。

4. 飛書群裡 @ 機器人沒反應

先確認兩件事：

飛書開放平臺裡的機器人權限和事件訂閱已經配好。
你已經啟動了網關，並用 hermes gateway run -vv 看到了正常日誌。

如果日誌沒報錯，但群裡依然不響應，可以先把群策略放寬為 open 進行排查：

Add-Content "$env:LOCALAPPDATA\hermes\.env" "`nFEISHU_GROUP_POLICY=open" -Encoding UTF8

然後重新運行：

$env:PYTHONUTF8 = '1'
hermes gateway run -vv

如果這樣能恢復，再回頭逐步收緊白名單配置。

Windows 用戶的推薦上手順序

大多數 Windows 用戶可以先走 原生 PowerShell，直接運行 install.ps1。
安裝完成後，先用 hermes 和 hermes model 驗證 CLI 與模型配置。
再去接飛書、微信、Telegram 等消息網關。
如果你偏好 Linux / Ubuntu 終端，或明確需要 POSIX 語義、Linux 文件監聽、Dashboard 內嵌終端等能力，再選擇 WSL2。

補充閱讀

安裝總覽
快速入門
飛書接入文檔
提供商配置與 WSL2 網絡說明
參考來源：阿里雲文章《Windows 也能跑 Hermes Agent！完整安裝教程 + 飛書接入，全程避坑》

先回答三個問題​

1. 什麼是 PowerShell？​

2. 怎麼打開 PowerShell？​

3. 什麼時候需要管理員 PowerShell？​

WSL2 到底是什麼？​

現在還必須裝 WSL2 嗎？​

安裝了 WSL2 之後，你實際會怎麼用？​

先決定走哪條路徑​

方案一：原生 PowerShell（推薦直接安裝）​

一鍵安裝​

原生 Windows 安裝後文件大致在哪裡​

方案二：WSL2（可選）​

第一步：在管理員 PowerShell 中安裝 WSL2​

第二步：在 WSL2 終端裡運行 Linux 安裝命令​

第三步：繼續配置模型​

飛書接入：Windows 用戶最容易踩的坑​

1. 先完成 Hermes 本體安裝，再單獨配置網關​

2. 如果報 lark-oapi 未安裝​

3. 如果網關一啟動就退出，或看到 WinError 11​

4. 飛書群裡 @ 機器人沒反應​

Windows 用戶的推薦上手順序​

補充閱讀​