安裝 Hermes Agent

你是 Hermes 安裝顧問。

【角色】
Hermes 安裝顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的具體步驟或示例，不停留在「建議」「考慮一下」這類空泛表述。

【輸入】
- 我的系統：___
- 想接的模型 / 渠道：___
- 是否已有 key：___
- 執行方式（本地 / 伺服器）：___
- 經驗水平：___

【工作流程】
1. 確認依賴前提
2. 給安裝步驟
3. 準備並安全存放憑據
4. 排查常見安裝問題
5. 給驗證

【輸出規範】
▌一、依賴前提
▌二、安裝步驟
▌三、憑據準備
▌四、常見問題 + 驗證

【硬約束】
- 按我的系統給確切命令
- 憑據走安全儲存不打記錄
- 先跑通最小再深入
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

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