適用日期：2026-05-18

適用對(duì)象：需要在 Windows、macOS、Linux、WSL2、Android Termux、Nix/NixOS 或服務(wù)器環(huán)境中安裝 Hermes Agent 的用戶。

主要參考：NousResearch/hermes-agent 官方倉(cāng)庫(kù)與官方文檔。安裝命令、平臺(tái)狀態(tài)和功能支持可能隨版本變化，執(zhí)行前建議再打開官方文檔確認(rèn)一次。

1. Hermes Agent 是什么

Hermes Agent 是 NousResearch 開源的個(gè)人 AI agent。它可以在命令行中對(duì)話、調(diào)用本地工具、執(zhí)行終端任務(wù)、連接消息平臺(tái)、安裝技能、使用 MCP 服務(wù)，并支持長(zhǎng)期會(huì)話、網(wǎng)關(guān)、計(jì)劃任務(wù)等功能。

本說明聚焦“從零安裝到可用”的完整流程，包含：

• 各操作系統(tǒng)安裝路徑；
• 環(huán)境依賴與目錄說明；
• 模型/API 配置；
• 安裝后驗(yàn)證；
• 更新、卸載、遷移與排障；
• 安全和注意事項(xiàng)。

2. 官方資料入口

建議優(yōu)先閱讀官方資料，避免使用來源不明的第三方安裝腳本。

• 官方倉(cāng)庫(kù)：https://github.com/NousResearch/hermes-agent
• 官方安裝文檔：https://github.com/NousResearch/hermes-agent/blob/main/website/docs/getting-started/installation.md
• 官方快速開始：https://github.com/NousResearch/hermes-agent/blob/main/website/docs/getting-started/quickstart.md
• 官方 CLI 命令參考：https://github.com/NousResearch/hermes-agent/blob/main/website/docs/reference/cli-commands.md

3. 安裝路徑選擇

4. 安裝前準(zhǔn)備

4.1 通用準(zhǔn)備

安裝前確認(rèn)：

git --version
curl --version

官方 Git 安裝器的核心前提是能訪問 GitHub，并且能拉?。?/p>

https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh

如果網(wǎng)絡(luò)環(huán)境無法訪問 GitHub raw 域名，安裝腳本會(huì)失敗。國(guó)內(nèi)網(wǎng)絡(luò)環(huán)境建議提前準(zhǔn)備代理或鏡像方案，但不要隨意運(yùn)行未知第三方腳本。

4.2 依賴說明

官方安裝器會(huì)自動(dòng)處理大部分依賴：

• uv：Python 包和虛擬環(huán)境管理；
• Python 3.11；
• Node.js 22；
• ripgrep；
• ffmpeg；
• Playwright/Chromium 相關(guān)瀏覽器能力；
• Hermes 倉(cāng)庫(kù)克隆、虛擬環(huán)境、全局 hermes 命令；
• 初始模型/工具配置向?qū)А?/li>

通常不需要手動(dòng)安裝 Python、Node.js、ripgrep、ffmpeg。真正需要提前確認(rèn)的是 git、curl、網(wǎng)絡(luò)訪問和終端權(quán)限。

4.3 模型/API 準(zhǔn)備

Hermes Agent 安裝后需要配置至少一個(gè)模型提供方。常見選擇：

推薦先只配置一個(gè)穩(wěn)定可用的模型，完成 CLI 聊天驗(yàn)證后，再添加 gateway、cron、skills、voice、MCP 等高級(jí)能力。

5. Linux 安裝

以下適用于 Ubuntu、Debian、Fedora、Arch、openSUSE 等主流 Linux。命令以 Debian/Ubuntu 為例。

5.1 安裝基礎(chǔ)工具

sudo apt update
sudo apt install -y git curl ca-certificates

驗(yàn)證：

git --version
curl --version

5.2 執(zhí)行官方安裝腳本

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安裝結(jié)束后重新加載 shell：

source ~/.bashrc
# 如果使用 zsh：
source ~/.zshrc

驗(yàn)證命令是否可用：

hermes --version
hermes doctor

5.3 Linux 安裝目錄

普通用戶安裝通常為：

代碼目錄：~/.hermes/hermes-agent/
命令入口：~/.local/bin/hermes
數(shù)據(jù)目錄：~/.hermes/

如果用 root/system-wide 方式安裝，官方文檔說明可能使用：

代碼目錄：/usr/local/lib/hermes-agent/
命令入口：/usr/local/bin/hermes
root 數(shù)據(jù)：/root/.hermes/ 或 HERMES_HOME 指定目錄

建議個(gè)人電腦使用普通用戶安裝，不要默認(rèn)用 sudo curl ... | sudo bash。

5.4 Linux 無 sudo/服務(wù)賬號(hào)安裝

如果 Hermes 要作為獨(dú)立服務(wù)賬號(hào)運(yùn)行，例如 hermes 用戶無 sudo 權(quán)限：

管理員先安裝 Chromium/Playwright 所需系統(tǒng)庫(kù)：

sudo npx playwright install-deps chromium

切換到服務(wù)用戶執(zhí)行普通安裝：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

確認(rèn) ~/.local/bin 在 PATH 中：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

驗(yàn)證：

hermes doctor

如果不需要瀏覽器自動(dòng)化，可以跳過瀏覽器組件：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-browser

6. macOS 安裝

6.1 安裝 Git 和命令行工具

macOS 通常需要先安裝 Xcode Command Line Tools：

xcode-select --install

也可以使用 Homebrew 安裝 Git：

brew install git

驗(yàn)證：

git --version
curl --version

6.2 執(zhí)行官方安裝腳本

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

macOS 默認(rèn) shell 多為 zsh，安裝后執(zhí)行：

source ~/.zshrc

驗(yàn)證：

hermes --version
hermes doctor

6.3 macOS 注意事項(xiàng)

• 如果終端提示 hermes: command not found，先重新打開終端，或確認(rèn) ~/.local/bin 是否在 PATH 中。
• 如果 Playwright/Chromium 下載失敗，多半是網(wǎng)絡(luò)問題，先解決 GitHub/npm/Playwright 的訪問。
• 如果系統(tǒng)彈出安全提示，確認(rèn)你運(yùn)行的是官方 GitHub 倉(cāng)庫(kù)腳本，不要放行不明來源腳本。

7. Windows 安裝

Windows 有兩條路：推薦 WSL2，或使用原生 PowerShell beta 安裝。

7.1 推薦方案：Windows + WSL2

這是當(dāng)前更穩(wěn)妥的 Windows 路徑，適合長(zhǎng)期使用。

7.1.1 安裝 WSL2

以管理員身份打開 PowerShell：

wsl --install

如需指定 Ubuntu：

wsl --install -d Ubuntu

安裝完成后重啟電腦，打開 Ubuntu 終端，創(chuàng)建 Linux 用戶。

7.1.2 在 WSL2 中安裝基礎(chǔ)工具

在 Ubuntu/WSL2 終端執(zhí)行：

sudo apt update
sudo apt install -y git curl ca-certificates

7.1.3 在 WSL2 中安裝 Hermes Agent

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
hermes doctor

7.1.4 WSL2 注意事項(xiàng)

• Windows 文件系統(tǒng)路徑如 C:\Users\... 在 WSL 中通常映射到 /mnt/c/Users/...。
• 如果要讓 Hermes 操作項(xiàng)目文件，建議把項(xiàng)目放在 WSL 的 Linux 文件系統(tǒng)內(nèi)，例如 ~/projects，性能和權(quán)限更穩(wěn)定。
• WSL2 安裝的數(shù)據(jù)位于 Linux 用戶的 ~/.hermes，與 Windows 原生安裝互不沖突。

7.2 Windows 原生 PowerShell 安裝：early beta

官方文檔標(biāo)注 Windows 原生支持仍是 early beta。普通用戶建議優(yōu)先使用 WSL2。確實(shí)要原生安裝時(shí)，打開 PowerShell 執(zhí)行：

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

安裝器會(huì)處理：

• uv；
• Python 3.11；
• Node.js 22；
• ripgrep；
• ffmpeg；
• PortableGit/Git Bash；
• Hermes 倉(cāng)庫(kù)和虛擬環(huán)境；
• 用戶 PATH 中的 hermes 命令。

安裝完成后關(guān)閉并重新打開 PowerShell：

hermes --version
hermes doctor

原生 Windows 默認(rèn)目錄：

代碼目錄：%LOCALAPPDATA%\hermes\hermes-agent
Git 目錄：%LOCALAPPDATA%\hermes\git
數(shù)據(jù)目錄：%LOCALAPPDATA%\hermes

原生 Windows 當(dāng)前注意事項(xiàng)：

• 官方文檔說明大部分 CLI、gateway、cron、browser tool、MCP 能力可原生運(yùn)行；
• Dashboard 的 /chat 終端面板依賴 POSIX PTY，官方說明仍需要 WSL2；
• 若遇到編碼問題，可按官方說明嘗試設(shè)置 HERMES_DISABLE_WINDOWS_UTF8=1 排查；
• 不建議在 Windows CMD 中執(zhí)行安裝命令，使用 PowerShell。

8. Android Termux 安裝

Hermes Agent 官方安裝腳本會(huì)自動(dòng)識(shí)別 Termux，并切換到 Android/Termux 流程。

8.1 安裝 Termux

建議從 F-Droid 安裝新版 Termux，不建議使用長(zhǎng)期未更新的應(yīng)用商店舊版。

8.2 更新 Termux 并安裝基礎(chǔ)工具

pkg update
pkg upgrade
pkg install git curl

8.3 執(zhí)行官方安裝腳本

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

官方文檔說明 Termux 路徑會(huì)：

• 使用 pkg 安裝系統(tǒng)依賴；
• 用 python -m venv 創(chuàng)建虛擬環(huán)境；
• 自動(dòng)設(shè)置 Android wheel 構(gòu)建所需環(huán)境；
• 優(yōu)先安裝 Termux 相關(guān) extras；
• 默認(rèn)跳過未經(jīng)充分驗(yàn)證的瀏覽器/WhatsApp 引導(dǎo)。

8.4 Termux 注意事項(xiàng)

• 手機(jī)端性能、內(nèi)存、后臺(tái)保活都比桌面/服務(wù)器弱；
• 不建議一開始啟用過多后臺(tái) gateway；
• 如果需要 24/7 在線，優(yōu)先考慮 VPS 或家用服務(wù)器。

9. Nix/NixOS 安裝

如果你使用 NixOS、macOS + Nix、Linux + Nix，建議按官方 Nix/NixOS 指南走 flake 或 declarative module 路徑。

注意事項(xiàng)：

• 不要同時(shí)混用 Nix 管理的 Python/Node 與普通安裝器生成的虛擬環(huán)境，除非你明確知道 PATH 和依賴來源；
• NixOS 上瀏覽器、系統(tǒng)庫(kù)、服務(wù)權(quán)限建議全部寫入配置；
• 如果只是普通用戶試用，非 Nix 系統(tǒng)可優(yōu)先使用官方 install.sh。

10. PyPI 安裝方式

如果你希望安裝 PyPI 發(fā)布版本，而不是跟蹤 main 分支：

pip install hermes-agent
hermes postinstall

說明：

• PyPI 版本通常跟隨 tagged release，不一定包含 main 最新提交；
• hermes postinstall 會(huì)安裝/配置 Node.js、瀏覽器、ripgrep、ffmpeg 等后置組件；
• 適合追求可復(fù)現(xiàn)版本的環(huán)境；
• 如果你需要最新功能，官方 quickstart 推薦使用 Git 安裝器。

11. 初始配置

安裝完成后，先運(yùn)行完整向?qū)В?/p>

hermes setup

或只配置模型：

hermes model

也可以分別配置：

hermes tools
hermes gateway setup
hermes config set

推薦順序：

1. hermes doctor 檢查環(huán)境；
2. hermes model 配置一個(gè)模型；
3. hermes 進(jìn)入聊天；
4. 讓它回答一個(gè)簡(jiǎn)單問題；
5. 再配置 gateway、skills、MCP、voice 等擴(kuò)展能力。

12. 驗(yàn)證安裝是否成功

12.1 基礎(chǔ)檢查

hermes --version
hermes doctor

12.2 啟動(dòng)聊天

hermes

進(jìn)入后輸入：

你好，簡(jiǎn)單介紹一下你當(dāng)前能使用的工具。

12.3 測(cè)試會(huì)話恢復(fù)

退出后執(zhí)行：

hermes --continue
# 或
hermes -c

如果能恢復(fù)上一段對(duì)話，說明基礎(chǔ)會(huì)話保存正常。

12.4 測(cè)試工具能力

在 Hermes 對(duì)話中輸入：

查看當(dāng)前目錄下有哪些文件。

如果 Hermes 能調(diào)用終端并返回結(jié)果，說明 terminal tool 基礎(chǔ)能力可用。

13. 常用功能開通

13.1 Gateway 消息平臺(tái)

基礎(chǔ)聊天成功后再配置：

hermes gateway setup

可按官方支持情況連接 Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant、Microsoft Teams 等平臺(tái)。

排查狀態(tài)：

hermes gateway status

13.2 Skills

搜索技能：

hermes skills search kubernetes

安裝技能：

hermes skills install openai/skills/k8s

也可在聊天中使用 /skills。

13.3 MCP 服務(wù)器

示例配置片段：

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

注意：不要把真實(shí) token 提交到 Git 倉(cāng)庫(kù)。建議使用環(huán)境變量、密鑰管理器或本機(jī)私有配置文件。

13.4 Docker/遠(yuǎn)程終端隔離

如果擔(dān)心 agent 直接操作本機(jī)，可考慮把 terminal backend 放到 Docker 或遠(yuǎn)程服務(wù)器：

hermes config set terminal.backend docker
hermes config set terminal.backend ssh

實(shí)際啟用前應(yīng)確認(rèn) Docker/SSH 的權(quán)限邊界、掛載目錄和網(wǎng)絡(luò)訪問范圍。

13.5 Voice 模式

官方 quickstart 中的示例：

cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"

然后在 CLI 中：

/voice on

按官方說明可用快捷鍵錄音。語(yǔ)音依賴較多，如安裝失敗，先確?；A(chǔ) CLI 和模型可用。

14. 更新

常規(guī)更新：

hermes update

檢查更新：

hermes update --check

更新前備份：

hermes update --backup

更新后重啟 gateway：

hermes update --restart-gateway

注意事項(xiàng)：

• 更新前建議先運(yùn)行 hermes doctor，記錄當(dāng)前狀態(tài)；
• 長(zhǎng)期運(yùn)行的 gateway 建議在低峰期更新；
• 如果本地修改過 Hermes 源碼，git pull 可能因工作區(qū)變更而失??；
• 重要生產(chǎn)環(huán)境建議先備份 HERMES_HOME。

15. 卸載

常規(guī)卸載：

hermes uninstall

刪除配置和數(shù)據(jù)：

hermes uninstall --full

無人值守確認(rèn)：

hermes uninstall --full --yes

卸載前建議備份：

cp -a ~/.hermes ~/.hermes.backup.$(date +%Y%m%d)

Windows 原生安裝的配置/數(shù)據(jù)在：

%LOCALAPPDATA%\hermes

WSL2/Linux/macOS 通常在：

~/.hermes

如果卸載后重裝仍出現(xiàn)舊 profile、舊 session、舊配置導(dǎo)致的問題，優(yōu)先檢查數(shù)據(jù)目錄是否殘留。

16. 常見問題

16.1hermes: command not found

處理：

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

仍不行則檢查：

echo $PATH
ls -l ~/.local/bin/hermes

Windows 原生安裝后需要關(guān)閉并重新打開 PowerShell。

16.2API key not set

運(yùn)行：

hermes model

或使用配置命令寫入對(duì)應(yīng) key，例如：

hermes config set OPENROUTER_API_KEY your_key

更推薦用交互向?qū)?，避?key 名寫錯(cuò)。

16.3 模型能連上但回答異常

可能原因：

• base URL 寫錯(cuò)；
• model name 寫錯(cuò)；
• 代理服務(wù)并非真正 OpenAI-compatible；
• provider fallback 或 routing 配置過于復(fù)雜。

建議先關(guān)閉高級(jí)路由，只保留一個(gè)模型，運(yùn)行：

hermes model
hermes doctor
hermes

16.4 Gateway 啟動(dòng)但收不到消息

檢查：

hermes gateway status
hermes gateway setup

重點(diǎn)看：

• bot token 是否正確；
• allowlist 是否限制了用戶；
• 平臺(tái) webhook/權(quán)限是否配置完成；
• gateway 是否在正確 profile 下運(yùn)行。

16.5hermes --continue找不到舊會(huì)話

檢查：

hermes sessions list

可能原因：

• 切換了 profile；
• 舊會(huì)話沒有保存；
• HERMES_HOME 指到了另一個(gè)目錄；
• WSL2 與 Windows 原生安裝混用，數(shù)據(jù)目錄不同。

16.6 Playwright/Chromium 安裝失敗

常見原因：

• Linux 缺少系統(tǒng)庫(kù)；
• 無 sudo 權(quán)限；
• 網(wǎng)絡(luò)無法下載瀏覽器；
• 企業(yè)網(wǎng)絡(luò)攔截 npm/Playwright 下載。

可選方案：

sudo npx playwright install-deps chromium

或跳過瀏覽器能力：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-browser

16.7 Windows 原生編碼或終端異常

先確認(rèn)是否必須原生運(yùn)行。如果不是，建議改用 WSL2。

原生排查可嘗試：

$env:HERMES_DISABLE_WINDOWS_UTF8="1"
hermes doctor

如果問題消失，再考慮把該環(huán)境變量寫入用戶環(huán)境變量。

17. 安全注意事項(xiàng)

1. 只運(yùn)行官方倉(cāng)庫(kù)腳本，安裝前確認(rèn) URL 是 NousResearch/hermes-agent。
2. 不要把 API key、GitHub token、SSH key 寫進(jìn)公開倉(cāng)庫(kù)。
3. 第一次運(yùn)行 agent 時(shí)，不要直接給它全盤寫權(quán)限；先在測(cè)試目錄里驗(yàn)證。
4. 生產(chǎn)服務(wù)器建議使用獨(dú)立低權(quán)限用戶運(yùn)行 Hermes。
5. 需要瀏覽器、文件、終端、網(wǎng)絡(luò)能力時(shí)，逐項(xiàng)開啟，不要一次性 開放全部工具。
6. 重要目錄操作前先備份。
7. 如果讓 Hermes 連接 Telegram/Discord/Slack 等平臺(tái)，務(wù)必設(shè)置 allowlist 或等價(jià)權(quán)限控制。
8. 對(duì)長(zhǎng)期在線的 gateway，要關(guān)注日志、更新節(jié)奏和 token 輪換。

18. 推薦完整安裝流程

新用戶按這個(gè)順序最穩(wěn)：

# 1. 檢查基礎(chǔ)工具
git --version
curl --version

# 2. 安裝 Hermes Agent
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 3. 重新加載 shell
source ~/.bashrc

# 4. 檢查環(huán)境
hermes doctor

# 5. 配置模型
hermes model

# 6. 啟動(dòng)聊天
hermes

# 7. 測(cè)試恢復(fù)會(huì)話
hermes --continue

Windows 用戶推薦把第 2 步放到 WSL2 的 Ubuntu 終端中執(zhí)行。

19. 速查命令

20. 最后建議

不要一裝完就同時(shí)開啟 gateway、cron、voice、browser、MCP 和多個(gè) provider。最穩(wěn)的方式是：

1. 先讓 CLI 能穩(wěn)定回答；
2. 再讓 terminal tool 正常工作；
3. 再配置一個(gè)消息平臺(tái)；
4. 再加 skills/MCP；
5. 最后考慮長(zhǎng)期后臺(tái)運(yùn)行和隔離策略。

這樣出問題時(shí)，每一步都有清晰的回退點(diǎn)。

以上就是20256年Hermes Agent的安裝全流程說明的詳細(xì)內(nèi)容，更多關(guān)于Hermes Agent安裝的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論