Hermes Agent中安裝踩坑記錄及解決方案
我要評論網(wǎng)上很多手把手安裝的教程已經(jīng)很詳細(xì)了，大多數(shù)都是一把過，但都沒有把其中每一步安裝的問題暴露出來，都是貼出成功的截圖，真實(shí)的是由于環(huán)境的復(fù)雜性從第一步就碰到了問題，其中大部分都是貼問題給deepseek或kimi來一步一個(gè)坑的來解決，反復(fù)折騰，現(xiàn)在復(fù)盤記錄下大部分的問題。
一、環(huán)境準(zhǔn)備：WSL2 安裝
win10安裝Hermes，Hermes 原生不支持 Windows，推薦優(yōu)先安裝Ubuntu虛擬機(jī)，再在虛擬機(jī)里面安裝hermes。
Windows 要先開 WSL2（Windows Subsystem for Linux 2），在 Windows 里開一個(gè) Linux 夾層。 你不是裝第二個(gè)操作系統(tǒng)，你是給 Windows 加一個(gè)插件。
系統(tǒng)要求
Windows11任意版本 / Windows 10 要 ≥ 2004。
啟用 WSL2
管理員身份打開 PowerShell，執(zhí)行
# 啟用 WSL dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # 啟用虛擬機(jī)平臺(tái)（WSL2 必需） dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
執(zhí)行完后重啟電腦
設(shè)置 WSL 默認(rèn)版本為 2
wsl --set-default-version 2 # 查看當(dāng)前狀態(tài)，確認(rèn)沒有報(bào)錯(cuò),沒有報(bào)錯(cuò)，說明 WSL2 修復(fù)成功 wsl --status
提示需要更新 WSL2 Linux 內(nèi)核，下載并安裝 wsl_update_x64.msi
安裝完更新包后，再次執(zhí)行上面的命令
二、常見安裝問題及解決方案
以管理員身份打開 PowerShell，輸入命令 wsl --install
問題1：提示無效的install，需要升級wsl
更新wsl異常
wsl --update 正在檢查更新... 正在下載更新... 正在安裝更新... 這個(gè)處理器類型不支持該安裝程序包。請與產(chǎn)品供應(yīng)商聯(lián)系。
說明當(dāng)前 Windows 系統(tǒng)架構(gòu)（32位/64位/ARM）與 WSL2 更新包不匹配，或者 CPU 不支持虛擬化。
下載并安裝 wsl_update_x64.msi，雙擊安裝，完成后重啟電腦
再執(zhí)行
wsl --set-default-version 2 wsl --install -d Ubuntu-20.04
install等待部署完成， 重新啟動(dòng)電腦。
問題2：win10安裝Ubuntu異常錯(cuò)誤代碼: 0x80072ee7
正在下載: Ubuntu 20.04 LTS 安裝過程中出現(xiàn)錯(cuò)誤。分發(fā)名稱: 'Ubuntu 20.04 LTS' 錯(cuò)誤代碼: 0x80072ee7
提前下載指定版本 Ubuntu 20.04 LTS 或 Ubuntu（默認(rèn)最新版）安裝包。
雙擊解壓后的 ubuntu2004.exe，等待安裝完成
安裝完后設(shè)置 WSL2：
wsl --set-version Ubuntu-20.04 2 # 查看當(dāng)前狀態(tài)，確認(rèn)沒有報(bào)錯(cuò),沒有報(bào)錯(cuò)，說明 WSL2 修復(fù)成功 wsl --status
問題3：ubuntu2004.exe安裝異常，WSL2 內(nèi)核未安裝
雙擊ubuntu2004.exe后 Installing, this may take a few minutes... WslRegisterDistribution failed with error: 0x800701bc Error: 0x800701bc WSL 2 ?????????????????? https://aka.ms/wsl2kernel Press any key to continue...
雙擊下載的 wsl_update_x64.msi 文件
再設(shè)置默認(rèn) WSL 版本為 2
wsl --set-default-version 2 # 查看當(dāng)前狀態(tài)，確認(rèn)沒有報(bào)錯(cuò),沒有報(bào)錯(cuò)，說明 WSL2 修復(fù)成功 wsl --status
再次雙擊 ubuntu2004.exe
手動(dòng)安裝 MSI 也報(bào)錯(cuò)"處理器類型不支持"說明你的系統(tǒng)或 CPU 確實(shí)不支持 WSL2，需要降級到 WSL1（不要使用WSL1，后面有其它組件版本不支持）：
# 設(shè)置默認(rèn)使用 WSL1 wsl --set-default-version 1
重新雙擊 ubuntu2004.exe 安裝即可。
WSL1 同樣可以編譯安裝 Hermes，只是性能稍差，不影響使用。
問題4：安裝完wsl_update_x64.msi后 再雙擊ubuntu2004.exe 還是異常，CPU 虛擬化未開啟
Installing, this may take a few minutes... WslRegisterDistribution failed with error: 0x80370102 Error: 0x80370102 ???????????????????
錯(cuò)誤 0x80370102 通常表示 BIOS/UEFI 中 CPU 虛擬化未開啟，或者 Windows 虛擬機(jī)平臺(tái)功能未生效。
1.PowerShell 執(zhí)行以下命令，彈出的窗口看版本號2004（Build 19041）是支持wsl2的。
winver
2.檢查 CPU 虛擬化是否開啟
打開任務(wù)管理器=>點(diǎn)擊 性能 標(biāo)簽頁=>點(diǎn)擊左側(cè) CPU=>右下角看 "虛擬化" 狀態(tài)：已啟用
3.確認(rèn) Windows 功能已啟用
PowerShell，重新執(zhí)行：
# 啟用虛擬機(jī)平臺(tái)（WSL2 必需） dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 啟用 Hyper-V（部分系統(tǒng)需要） dism.exe /online /enable-feature /featurename:Microsoft-Hyper-V /all /norestart
執(zhí)行完重啟電腦，然后再雙擊 ubuntu2004.exe。
總之還沒到安裝hermes一步就在wsl和ubuntu系統(tǒng)之間反復(fù)的折騰。
終于正常進(jìn)入ubuntu系統(tǒng)了，進(jìn)行安裝hermes。
三、Hermes 安裝問題
問題5： WSL 1 is not supported. Please upgrade to WSL 2
ubuntu中運(yùn)行npm install -g hermes-web-ui異常 WSL 1 is not supported. Please upgrade to WSL 2 or above.
Could not determine Node.js install directory
之前安裝wsl2失敗，就用了wsl1來試，結(jié)果報(bào)以上異常，看來必須用wsl2，就按以上步驟來修復(fù)安裝wsl2。
安裝完成后 WSL2 Ubuntu 中安裝 hermes-web-ui
# 安裝 Node.js sudo apt update sudo apt install -y nodejs npm # 安裝 hermes-web-ui sudo npm install -g hermes-web-ui # 啟動(dòng) hermes-web-ui start
默認(rèn)版本： node v10.19.0 和 npm6.14.4
再次遇到 Could not determine Node.js install directory 錯(cuò)誤，改用以下方式：
mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc source ~/.bashrc npm install -g hermes-web-ui
啟動(dòng)后hermes-web-ui后
在 Ubuntu 終端中執(zhí)行以下命令查看端口監(jiān)聽情況：
ss -tlnp | grep 8648 # 或者 netstat -tlnp | grep 8648
問題6：npm install -g hermes-web-ui運(yùn)行異常，Node.js 版本過低
Rebuilding because directory /usr/local/lib/node_modules/hermes-web-ui/node_modules/node-pty/prebuilds/linux-x64 does not exist
gyp ERR! configure error
gyp ERR! stack Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/hermes-web-ui/node_modules/node-pty/build'
gyp ERR! System Linux 4.4.0-19041-Microsoft
gyp ERR! command "/usr/bin/node" "/usr/bin/node-gyp" "rebuild"
gyp ERR! cwd /usr/local/lib/node_modules/hermes-web-ui/node_modules/node-pty
gyp ERR! node -v v10.19.0
gyp ERR! node-gyp -v v6.1.0
gyp ERR! not ok
npm WARN notsup Unsupported engine for hermes-web-ui@0.5.32: wanted: {"node":">=23.0.0"} (current: {"node":"10.19.0","npm":"6.14.4"})
npm WARN notsup Not compatible with your version of node/npm: cliui@8.0.1
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! node-pty@1.1.0 install: `node scripts/prebuild.js || node-gyp rebuild`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the node-pty@1.1.0 install script.
npm ERR! 'Error: EACCES: permission denied, access \'/usr/local/lib\''
……
兩個(gè)原因?qū)е率。?/strong>
- Node.js 版本太老：Ubuntu 20.04 默認(rèn)源里的 Node.js 是 v10.19.0，但
hermes-web-ui要求 Node.js >= 23.0.0 - 權(quán)限問題：用
sudo npm install -g安裝會(huì)導(dǎo)致系統(tǒng)目錄權(quán)限混亂
解決方案：用 nvm 安裝新版 Node.js
nvm（Node Version Manager）可以安裝任意版本的 Node.js，且不需要 sudo。
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
再用nvm安裝Node.js 23
nvm install 23 再重裝hermes-web-ui npm install -g hermes-web-ui
問題7：nvm安裝異常 curl: (7) Failed to connect toraw.githubusercontent.comport 443: Connection refused
國內(nèi)訪問 GitHub 被攔截了，用 Gitee 國內(nèi)鏡像 安裝 nvm：
# 用 Gitee 鏡像下載 nvm 安裝腳本 curl -o- https://gitee.com/mirrors/nvm/raw/v0.39.7/install.sh | bash
安裝完后，重新打開一個(gè) Ubuntu 終端（或執(zhí)行 source ~/.bashrc），然后：
# 配置 nvm 使用國內(nèi) Node.js 鏡像（下載更快） export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node # 安裝 Node.js 23 nvm install 23 # 驗(yàn)證版本 node -v # 應(yīng)顯示 v23.x.x npm -v # 應(yīng)顯示 10.x.x
問題8：nvm 命令找不到
Command 'nvm' not found
運(yùn)行curl -o- https://gitee.com/mirrors/nvm/raw/v0.39.7/install.sh | bash后 nvm --version Command 'nvm' not found, did you mean: command 'lvm' from deb lvm2 (2.03.07-1ubuntu1)
終端會(huì)話沒有加載 nvm 的環(huán)境變量
# 手動(dòng)把 nvm 配置寫入 .bashrc echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.bashrc # 重新加載 source ~/.bashrc # 驗(yàn)證 nvm --version
問題9：nvm install 23 返回Computing checksum with sha256sum
Checksums matched! Your project npmrc file (/mnt/c/Users/Administrator/.npmrc) has a `globalconfig` and/or a `prefix` setting, which are incompatible with nvm. Run `nvm use --delete-prefix v23.11.1` to unset it.
這個(gè)錯(cuò)誤是因?yàn)?Windows 上的 npm 配置干擾了 WSL2 里的 nvm。
你的 Windows 用戶目錄（C:\Users\Administrator）里有一個(gè) .npmrc 文件，里面設(shè)置了 prefix 或 globalconfig，WSL2 掛載了 Windows 磁盤，npm 讀取到了這個(gè)配置，與 nvm 沖突。
解決方法
在 Ubuntu 終端中執(zhí)行提示的命令：
nvm use --delete-prefix v23.11.1
nvm use --delete-prefix v23.11.1命令返回unexpected
/home/james/.nvm/versions/node/v23.11.1/bin/node: 1: Syntax error: ")" unexpected /home/james/.nvm/versions/node/v23.11.1/bin/node: 1: Syntax error: ")" unexpected
這個(gè)錯(cuò)誤說明 Node.js 23 的二進(jìn)制文件與你的 WSL2 環(huán)境不兼容。原因很可能是：
- WSL2 的 Linux 內(nèi)核版本較老（你之前顯示
5.10.16） - 或者 nvm 下載的 Node.js 23 是 ARM64 架構(gòu)而非 x64
此處建議我安裝node20(后面排查不是node版本問題，還是用23的版本),但安裝后又出現(xiàn)異常
npm -v 輸出npm error config prefix cannot be changed from project config: /mnt/c/Users/Administrator/.npmrc. 10.8.2
node.js 20 安裝成功，但 Windows 的 .npmrc 文件還在干擾 npm。直接處理掉：
移除 Windows 的 .npmrc 干擾
# 備份并刪除 Windows 用戶的 .npmrc mv /mnt/c/Users/Administrator/.npmrc /mnt/c/Users/Administrator/.npmrc.bak # 重新加載 nvm source ~/.bashrc # 驗(yàn)證 npm 是否正常 npm -v
四、運(yùn)行時(shí)問題
問題10：API 調(diào)用 502 錯(cuò)誤
重新配置以上模型后 對話輸入內(nèi)容后 Error: API Error 502: {“error”:{“message”:“Proxy error: fetch failed”}}
502 Proxy error: fetch failed 說明 hermes-web-ui 這個(gè)應(yīng)用本身無法連到外部 API，但之前你直接用 curl 測試是成功的。這通常是 WSL2 網(wǎng)絡(luò)/代理環(huán)境問題
wsl里面運(yùn)行 curl https://api.deepseek.com/v1/models \
-H "Authorization: Bearer sk-xxxx“
正常返回{"object":"list","data":[{"id":"deepseek-v4-flash","object":"model","owned_by":"deepseek"},{"id":"deepseek-v4-pro","object":"model","owned_by":"deepseek"}]}；
運(yùn)行env | grep -i proxy命令 返回空；
說明 hermes-web-ui 內(nèi)部的請求轉(zhuǎn)發(fā)層出了問題，不是網(wǎng)絡(luò)或 Key 的問題。
后面檢查出是hermes網(wǎng)關(guān)沒有啟動(dòng)。
檢查網(wǎng)關(guān)是否正常運(yùn)行
在 WSL2 Ubuntu 終端中執(zhí)行：
# 查看 hermes-web-ui 進(jìn)程 ps aux | grep hermes # 查看端口監(jiān)聽 ss -tlnp | grep 8648 ss -tlnp | grep 3000 # 網(wǎng)關(guān)默認(rèn)可能跑在 3000 或其他端口
正常應(yīng)該看到至少兩個(gè)進(jìn)程：
- 一個(gè)監(jiān)聽
8648（Web UI 前端） - 一個(gè)監(jiān)聽另一個(gè)端口（網(wǎng)關(guān)后端）
問題11：網(wǎng)關(guān)沒有啟動(dòng)
hermes-web-ui 啟動(dòng)時(shí)應(yīng)該自動(dòng)啟動(dòng)網(wǎng)關(guān)。如果手動(dòng)關(guān)閉了或配置分離了，嘗試：
# 確保完整啟動(dòng)（包含網(wǎng)關(guān)） hermes-web-ui start --gateway
問題12：OpenRouter 免費(fèi)模型速率限制
用 https://openrouter.ai/api/v1 第一次會(huì)話能正常返回信息，第二次請求時(shí)就異常 API call failed
用 https://openrouter.ai/api/v1 第一次會(huì)話能正常返回信息，第二次請求時(shí)就異常 API call failed (attempt 3/3) error_type=RateLimitError thread=asyncio_0:140437168981760 provider=custom base_url=https://openrouter.ai/api/v1 model=deepseek/deepseek-v4-flash:free summary=HTTP 429: Provider returned error 2026-05-21 17:12:59,243 ERROR [mpf9qgqnev5sm9] root: API call failed after 3 retries. HTTP 429: Provider returned error | provider=custom model=deepseek/deepseek-v4-flash:fre
OpenRouter 的免費(fèi)模型有速率限制：通常是 10-20 請求/分鐘，你第一次請求后，第二次觸發(fā)限流了。這是 OpenRouter 免費(fèi) tier 的正常行為，無法繞過
到此這篇關(guān)于Hermes Agent中安裝踩坑記錄及解決方案的文章就介紹到這了,更多相關(guān)Hermes Agent安裝內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！
相關(guān)文章
Hermes Agent 桌面版安裝部署完全指南：一步步安裝自進(jìn)化Agent智能體
Hermes Agent 是由 Nous Research 開發(fā)的開源自主 AI 智能體（MIT 協(xié)議），這篇文章給大家介紹Hermes Agent 桌面版安裝部署完全指南：一步步安裝自進(jìn)化Agent智能體，感興趣2026-07-02
最近在開源 Agent 圈里，Hermes Agent 的名字反復(fù)出現(xiàn)在各種討論中,有人戲稱它為愛馬仕 Agent，這篇文章將從零開始部署 Hermes Agent 并接入飛書的完整過程做一個(gè)系統(tǒng)梳理2026-06-14
從0到1的Hermes Agent的保姆級教程詳細(xì)學(xué)習(xí)與使用指南
本文將手把手帶你從零開始，全面了解 Hermes Agent 的核心特性、安裝部署方法、配置技巧以及進(jìn)階使用指南,無論你是技術(shù)小白還是資深開發(fā)者，都能通過這篇保姆級教程，打造2026-05-30
Hermes Agent安裝、運(yùn)行、使用常見錯(cuò)誤總結(jié)與解決方案
本文提供了HermesAgent在Windows、WSL2、macOS、Linux及Termux等環(huán)境下的使用指南,包括常見錯(cuò)誤排查、診斷命令、安裝階段常見錯(cuò)誤、運(yùn)行階段常見錯(cuò)誤等，希望可以幫助用戶2026-05-19
Hermes Agent 安裝部署攻略60秒入門這個(gè)可成長的AI助手
HermesAgent是一個(gè)自主運(yùn)行的的A自主學(xué)習(xí)的AI代理,支持多多平臺(tái),具有自主成長、跨會(huì)話會(huì)議和記憶的特點(diǎn),文章介紹安裝和配置過程,,及使用、技能管理和定時(shí)任務(wù)的簡要使用，2026-05-19- Hermes Agent 是 NousResearch 開源的個(gè)人 AI 助手，支持跨平臺(tái)安裝（Windows/macOS/Linux/WSL2/Android/NixOS）,本文提供從零安裝指南，涵蓋環(huán)境準(zhǔn)備、依賴處理、模型配2026-05-18
macOS系統(tǒng)下安裝與配置Hermes Agent的完整指南(收藏這一篇就夠了)
Hermes Agent 支持 macOS，但安裝過程有幾個(gè)點(diǎn)需要注意,本文是 macOS 專屬安裝指南，覆蓋從零配置到運(yùn)行的全流程，以 MiniMax 為例演示 AI 提供商配置,有需要的小伙伴可以2026-05-11
本文詳細(xì)介紹了Hermes Agent的本地快速部署流程，涵蓋環(huán)境要求（Linux/macOS/WSL2），兩種安裝方式，API密鑰配置等內(nèi)容，希望可以幫助讀者輕松完成HermesAgent的安裝與配2026-05-08
