跳到主要內容

Windows 安裝

安裝遇到困難？
  • 點擊加入 中文社區微信群，提問並獲取群內專家幫助。
  • 如果您已經安裝了龍蝦 OpenClaw，或者國內常見的龍蝦版本，例如 QClaw、WorkBuddy、ArkClaw、AutoClaw，可以讓它讀文檔協助您配置，您自己不用懂任何技術細節。有兩種方式：

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

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

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

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

  • 安裝過程中遇到問題時，也可以先詢問 豆包、DeepSeek 等 AI 助手。

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

先回答三個問題​

1. 什麼是 PowerShell？​

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

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

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

  • 命令行
  • 終端
  • Shell
  • PowerShell

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

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

2. 怎麼打開 PowerShell？​

最簡單的方法：

  1. 按一下鍵盤左下角 Windows 鍵
  2. 輸入 PowerShell
  3. 點擊 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。

為什麼我們更推薦 WSL2？​

因為 Hermes Agent 的很多能力，本來就更貼近類 Unix 環境，例如：

  • shell / 終端工具鏈
  • Python / Node.js 依賴安裝
  • 瀏覽器自動化
  • Docker / SSH / MCP / 網關等擴展能力

這些在 WSL2 裡通常會比原生 PowerShell：

  • 更穩定
  • 更接近官方文檔
  • 少一些 Windows 特有兼容性問題

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

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

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

也就是說：

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

如果你看到文檔裡寫：

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

那麼這條命令就應該：

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

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

先決定走哪條路徑​

路徑適合誰推薦程度你要運行的命令
WSL2 + Ubuntu想要最穩的日常使用體驗，希望儘量貼近官方文檔、終端工具和自動化工作流強烈推薦在 WSL2 裡運行 install.sh
原生 PowerShell想先在 Windows 本機快速跑起來，不想先配置 WSL2可用，但更容易遇到兼容性問題在 PowerShell 裡運行 install.ps1
推薦結論
  • 長期使用 / 工具鏈完整 / 網關與自動化更省心：優先選 WSL2。
  • 只是想先在 Windows 本機跑通 CLI：可以直接用 PowerShell。
中國大陸網絡環境提示

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

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

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

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

如果你還沒裝過 WSL，建議先看這篇中文帖子：

然後再執行：

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

如果你只是需要一個最穩的 Windows 版本 Hermes，做到這裡就夠了。後續文檔默認也更偏向這條路徑。

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

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

方案二：原生 PowerShell（可用，但更容易踩坑）​

一鍵安裝​

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

  1. 按 Windows 鍵
  2. 輸入 PowerShell
  3. 點擊 Windows PowerShell 或 PowerShell
  4. 把下面這行命令完整複製進去
  5. 在 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 安裝後文件大致在哪裡​

默認安裝目錄通常在：

%LOCALAPPDATA%\hermes

例如：

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

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

飛書接入：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，導致網關異常退出。這是原生 Windows 路徑的兼容性問題，不是 WSL2 的常見問題。

如果你正好遇到這個問題，有兩種選擇：

  1. 最省心的辦法：改走 WSL2。
  2. 繼續堅持原生 PowerShell： 按阿里雲文章中的思路，對 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
注意

這是 原生 Windows 專用的臨時規避方案。如果你希望少踩坑，仍然建議優先回到 WSL2。

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

先確認兩件事：

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

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

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

然後重新運行：

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

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

  1. 先決定用 WSL2 還是 原生 PowerShell。
  2. 安裝完成後，先用 hermes 和 hermes model 驗證 CLI 與模型配置。
  3. 再去接飛書、微信、Telegram 等消息網關。
  4. 如果你要連接本地模型、Docker、瀏覽器自動化或各種 shell 工具，優先回到 WSL2 路徑。

補充閱讀​