安裝 Hermes Agent

Hermes Agent 的安裝本身不復雜。真正容易出錯的是：指令碼跑完後 shell 找不到 hermes 命令、provider（推理服務商）沒配置、~/.hermes/ 這個配置目錄看不懂、Termux 或 WSL2 環境誤用、或者一上來就接 Gateway（訊息閘道器）和 cron（定時任務）導致問題疊在一起沒法定位。

官方資料：Installation、Quickstart、GitHub README。

支援環境

官方安裝指令碼現在覆蓋五類環境：

Termux（Android 終端模擬器）走同一個 install.sh，但安裝器會自動檢測並切換到 Android 專用流程：用 Termux pkg 裝系統依賴（git、python、nodejs、ripgrep、ffmpeg），用 python -m venv 建立虛擬環境，自動設 ANDROID_API_LEVEL 讓 Python wheel（預編譯包）能正確構建，並裝精簡的 .[termux] extra。瀏覽器和 WhatsApp bootstrap（啟動）這類不穩定能力預設不啟用。

一行安裝

POSIX 系（Linux、macOS、WSL2、Termux）執行：

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

原生 Windows 開啟 PowerShell（早期測試，遇坑可切 WSL2）：

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

安裝前只需要先確認 git 可用：

git --version

官方安裝器會自動處理常見依賴：uv（Python 包管理器）、Python、Node.js、ripgrep（高速正則搜尋）、ffmpeg（音影片處理）等（具體版本號按官方 Installation 頁 當前要求為準，避免在教程裡寫死）。不要在安裝前手動混裝一堆 Python / Node 環境——先讓安裝器走完，再按報錯補缺口；提前裝的版本反而容易和安裝器期望版本衝突。

安裝器會做什麼

安裝器主要完成五件事：

1. 檢查系統和依賴。
2. 複製 Hermes Agent 儲存庫。
3. 建立 Python virtualenv（虛擬環境，把 Hermes 的依賴和系統 Python 隔離）。
4. 註冊全域性 hermes 命令（在 ~/.local/bin/ 下放一個 symlink 指向真正的入口指令碼）。
5. 引導你進入 LLM provider（推理服務商）配置——填 OpenAI / Anthropic / Nous Portal 等家的 API key 或 OAuth 憑據。

安裝成功的標準不是「指令碼沒有紅字」，而是 hermes 命令能被當前 shell 找到，並能進入幫助或模型配置。指令碼跑通了 ≠ 裝好了——下一節驗收命令入口才是真的標準。

安裝目錄

POSIX 系普通使用者安裝後，先記住這三個位置：

~/.hermes/hermes-agent/    Hermes Agent 源码（仓库本体 + virtualenv）
~/.local/bin/hermes        全局命令入口，通常是指向源码内启动脚本的 symlink
~/.hermes/                 配置、auth、skills、sessions、memory、logs（用户数据，可备份）

如果用 root-mode（sudo curl ... | sudo bash）做系統級安裝，官方路徑會變成類似：

/usr/local/lib/hermes-agent/    系统级源码位置（FHS 标准）
/usr/local/bin/hermes           系统级命令入口
/root/.hermes/ 或 HERMES_HOME   root 用户数据目录

原生 Windows 安裝路徑不同：原始碼放在 %LOCALAPPDATA%\hermes\hermes-agent，自帶的 portable Git 放在 %LOCALAPPDATA%\hermes\git，hermes 加進使用者級 PATH（不是系統級，不要 admin），資料在 %LOCALAPPDATA%\hermes。裝完一定要重啟終端或開新 PowerShell 視窗，PATH 才會生效。

個人學習和單使用者機器優先用普通使用者安裝。共享伺服器或統一運維場景才考慮 root-mode，並且要單獨規劃每個使用者的 HERMES_HOME 環境變數和金鑰邊界——不要讓所有使用者共享一份 ~/.hermes/ 資料。

安裝後第一步

POSIX 系安裝完成後先過載 shell，讓新加進 PATH 的 hermes 命令在當前終端生效。bash 使用者：

source ~/.bashrc

zsh 使用者：

source ~/.zshrc

原生 Windows 使用者關掉當前 PowerShell 視窗、開個新視窗，或在當前視窗執行 $env:Path 看 %LOCALAPPDATA%\hermes 是否在裡面。

然後驗收命令入口：

hermes --help
hermes model

hermes --help 能輸出幫助，說明 PATH 基本沒問題。hermes model 能進入互動配置，說明下一步可以配置 provider。

不要一開始全開功能

第一次安裝後的順序應該是：

install -> PATH check -> hermes model -> first chat -> session resume
（安装 → PATH 验证 → 配 provider → 第一次对话 → 会话恢复）

不要反過來先接 Telegram、Discord、Slack、WhatsApp、cron、MCP（模型上下文協議）、skills 或 browser automation（瀏覽器自動化）。基礎對話還沒跑通時，功能開得越多，排障越慢——同一個問題既可能在模型層、也可能在 toolset、也可能在 backend，最後變成「哪都可能錯」。

常見問題

hermes: command not found

先過載 shell（source ~/.zshrc 或 ~/.bashrc），再檢查 ~/.local/bin 是否真的在 PATH 裡：

echo $PATH | tr ':' '\n' | grep '\.local/bin'

如果你用的是 zsh 卻只改了 .bashrc，當前 shell 不會自動讀到——這是最常見誤區。原生 Windows 上則是沒重啟 PowerShell。

API key not set 或 provider 拒絕呼叫

執行 hermes model 重新配置 provider。金鑰應該寫入 Hermes 的配置路徑（~/.hermes/auth.json 或 .env），不要貼進公開儲存庫、普通 Markdown、shell 歷史命令或團隊聊天群——一旦提交進 git 歷史就很難真正撤回。

Termux 編譯失敗

先確認你在 Termux 原生環境裡直接執行官方指令碼，不是在 Android 上套了不受支援的 Linux 容器（如某些"Linux on Android" 應用）。再看 官方 Termux guide。

原生 Windows：裝完了但找不到命令

99% 是 PATH 沒重新整理。關掉當前 PowerShell 視窗、開新視窗，再 hermes --help。還不行就檢查 $env:Path 裡有沒有 %LOCALAPPDATA%\hermes。

更新後配置異常

先跑診斷命令，讓 Hermes 自己告訴你哪裡壞了：

hermes doctor
hermes config check

必要時再做配置遷移，不要直接 rm -rf ~/.hermes/——那會一併刪掉你所有的 session、memory 和已配的 skill。

安裝驗收清單

安裝完成後至少確認下面 6 條。任何一條不過，先停下排查，不要繼續往下接 provider、Gateway 或 cron：

• git --version 正常輸出。
• hermes --help 能列印幫助。
• hermes model 能開啟 provider 配置互動介面。
• ~/.hermes/ 目錄已建立（POSIX）或 %LOCALAPPDATA%\hermes 已建立（Windows native）。
• 你能用一句話解釋 config.yaml、.env、skills、sessions、memory 和 logs 大致放在哪裡、各管什麼。
• 沒有把任何 API key 寫進公開檔案、git 儲存庫或 shell history。

下一步

官方資料

• Installation 完整頁
• Quickstart
• Termux 專項 guide
• Updating & Uninstalling
• GitHub README