2026 Hermes Agent 全網最完整安裝與配置指南：保姆教程實戰案例從 0 到跑通

2. 痛點拆解

1. 限制：教程停在「啟動成功」。終端機裡出現歡迎語不等於模型連通、檔案工具可用或閘道能收訊息。Hermes 真正可用要同時完成環境核對、模型連通、權限邊界、日誌可追蹤和低風險案例驗收。
2. 隱性成本：金鑰與路徑散落。API Key 只貼在筆記裡、config.yaml 與 .env 不一致、工作區指向整個使用者主目錄——一次誤操作就可能改寫 SSH 金鑰或生產倉庫。
3. 穩定性與稽核：裝完就忘日誌在哪。出問題時盲目重裝，反而覆蓋掉 ~/.hermes/logs/errors.log 裡僅有的線索；也不做備份，升級後無法回滾配置。

3. 安裝前準備：Mac 與環境核對清單

目的：避免裝到一半才發現網路、Git 或磁碟不滿足要求。通過標準：下面清單全部打勾後再執行安裝腳本。

• 系統：macOS 12+（Intel 或 Apple Silicon 均可；Apple Silicon 上本機推理可選性更好，但雲端模型仍以 provider 文件為準）。
• Git：官方 git 安裝器唯一硬性前置是 Git（git --version ≥ 2.30 建議）。無 Git 時先裝 Xcode Command Line Tools 或 brew install git。
• 網路：需能存取 GitHub raw（安裝腳本）及你選的 LLM provider API；公司代理環境提前配置 HTTPS_PROXY。
• 磁碟：官方安裝會拉取 Python 3.11、Node.js v22、ripgrep、ffmpeg 與程式碼倉庫，建議預留 ≥ 2GB 可用空間（含 Skills 快取時更接近 1.5–3GB，以當時文件為準）。
• 權限：個人使用者安裝無需 sudo；若曾用 root 模式安裝，資料目錄可能在 /root/.hermes，與本文預設路徑不同。
• 備份：若已有舊版 ~/.hermes，先 cp -a ~/.hermes ~/.hermes.bak-$(date +%F)。
• 測試目錄：建立隔離工作區（下文統一用 ~/hermes-lab），不要把首次實戰指向 ~/Documents、生產 git 倉庫或含金鑰的目錄。

# 安裝前快速自檢（複製整段執行）
git --version
sw_vers
df -h ~
mkdir -p ~/hermes-lab/{inbox,outbox,archive}
echo "Hermes lab sample: Q2 planning notes." > ~/hermes-lab/inbox/sample.txt

失敗先看：Git 報錯 → CLT/Homebrew；磁碟不足 → 清理 Downloads 或換碟；網路逾時 → 換網路或鏡像，不要在未確認原因時連續重裝三遍。

4. 按官方方式安裝 Hermes Agent

目的：用 Nous Research 維護的安裝入口，讓安裝器自動處理 Python、Node 與 CLI。來源：官方 Installation 文件（發布前請再核對是否有新版本號或額外參數）。

4.1 推薦：Git 一鍵安裝（追蹤 main）

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

安裝器會自動完成：uv、Python 3.11、Node.js v22、ripgrep、ffmpeg、克隆倉庫、建立虛擬環境、將 hermes 加入 PATH。典型布局（per-user）：

• 程式碼：~/.hermes/hermes-agent/
• 資料與配置：~/.hermes/（可用 HERMES_HOME 覆蓋）
• CLI：~/.local/bin/hermes

4.2 備選：pip 安裝（需已有 Python 3.11+）

pip install hermes-agent
hermes postinstall   # 可選：補裝 Node、瀏覽器、ripgrep、ffmpeg 並跑 setup

PyPI 版本追蹤標籤發布；若要 bleeding-edge，仍建議用上面的 git 安裝腳本。兩種方式的 hermes update 行為不同，以 hermes doctor 顯示的安裝方式為準。

4.3 安裝後必做三步

source ~/.zshrc          # 或新開一個終端機視窗
hermes version           # 記錄版本號到筆記，便於日後排錯
hermes doctor            # 自動診斷缺失項；可加 --fix 嘗試修復

通過標準：which hermes 指向 ~/.local/bin/hermes；hermes doctor 無阻塞性 FAIL。失敗先看：安裝腳本最後 20 行日誌 → PATH → 是否混用系統 Python 直接執行倉庫內 hermes 檔案（應使用 venv 啟動器）。

切忌：安裝失敗後不要立刻「刪掉 ~/.hermes 再裝」——先保存終端機輸出與 hermes doctor 結果，否則難以區分是網路問題還是權限問題。

5. 配置模型與 API Key

目的：讓 Hermes 能呼叫你選的 LLM provider。通過標準：非互動式冒煙測試收到合理回覆；hermes auth list 或 .env 中有對應項且不在 shell history 明文長期停留。

5.1 互動式配置（首次推薦）

hermes setup          # 全量嚮導：模型、工具、閘道等
# 或分步：
hermes model          # 選擇 provider 與預設模型
hermes tools          # 按需啟用工具集

5.2 環境變數與配置檔案

主配置一般在 ~/.hermes/config.yaml；金鑰引用多在 ~/.hermes/.env（用 hermes config path、hermes config env-path 確認實際路徑）。範例（變數名以你所選 provider 的官方文件為準，勿照抄過期名稱）：

# 範例：OpenRouter（請替換為你的 key，勿提交到 git）
hermes config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# 或直接編輯 .env（chmod 600 ~/.hermes/.env）
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.hermes/.env

邊界提示：模型價格、API 限額、地區可用性與隱私政策會隨 provider 調整——上線前務必閱讀其最新條款。本文不綁定某一固定模型名。

6. 工作目錄、權限與日誌

目的：裝好後「可追蹤、可限制、可回滾」。原則：最小權限——先只允許動測試目錄，再逐步放開真實專案。

• 工作區：在 config.yaml 或工作階段中指定 ~/hermes-lab；可在該目錄放 AGENTS.md 描述允許的工具與邊界（參見官方 Context Files 文件）。
• macOS 權限：若啟用終端機/檔案類工具，系統可能提示「完整磁碟存取」——首次驗收階段可只授予測試目錄相關權限，避免對整個磁碟放權。
• 日誌目錄：預設 ~/.hermes/logs/（含 agent.log、errors.log、gateway.log）。用 hermes logs list、hermes logs errors --since 30m 查看。
• 金鑰安全：chmod 600 ~/.hermes/.env；備份 zip 不要放進同步碟；勿讓 Agent 讀取 ~/.ssh、支付或生產 kubeconfig。
• 背景執行（可選）：需要 Telegram/Discord 等閘道時，用 hermes gateway setup 與 hermes gateway install；長期維運見本站Hermes 長期維護指南。

通過標準：對 Agent 說「只讀寫 ~/hermes-lab」後，嘗試存取主目錄外路徑應被拒絕或在日誌中留下稽核記錄。

7. 首次執行驗收：七步 Runbook

下面七步把「配置完成」推到「實戰可用」的門檻——建議原樣執行並保存輸出截圖或日誌片段。

1. 診斷：hermes doctor --fix → 無未處理 FAIL。
2. 模型 ping：hermes chat -q "Reply with exactly: HERMES_OK" → 回覆含 HERMES_OK。
3. 檔案讀：讓 Agent 讀取 ~/hermes-lab/inbox/sample.txt 並複述首句。
4. 檔案寫：寫入 ~/hermes-lab/outbox/ping.txt → cat 可見。
5. 日誌：hermes logs errors --since 10m → 無新 ERROR（或已知可忽略項已記錄）。
6. 關終端機：關閉視窗，新開終端機重複步驟 2 → 排除 PATH 僅目前 session 生效。
7. 可選重啟：重啟 Mac 後再跑步驟 2（若已裝 gateway，再加 hermes gateway status）。

可引用閾值（個人驗收參考，非官方 SLA）：冒煙回覆 < 60s；errors.log 10 分鐘內 0 條未解釋 ERROR；測試檔案寫入後 ls -la ~/hermes-lab/outbox 可見新檔案。

8. 跑通第一個實戰案例：摘要 + 待辦 + 可回滾輸出

場景設計：在測試目錄讀取樣本文本，產生繁體中文摘要與 3 條待辦，寫入 Markdown，並保留回滾副本。該案例同時覆蓋安裝結果（CLI）、配置結果（模型）、真實 workflow（讀→推理→寫→日誌）。

# 1. 準備輸入（若第 3 節已建立可跳過）
cat > ~/hermes-lab/inbox/weekly-notes.txt <<'EOF'
本週完成：Hermes 安裝文件草稿。
待跟進：配置 OpenRouter 預算告警；下週評估 gateway 接 Telegram。
風險：勿把 API Key 提交到 git。
EOF

# 2. 啟動互動工作階段（或使用一條複合指令）
hermes
# 在工作階段中發送（範例提示詞）：
# 「請只使用 ~/hermes-lab 目錄。讀取 inbox/weekly-notes.txt，
#   用繁體中文寫 150 字以內摘要 + 3 條待辦，保存到 outbox/summary-and-todos.md，
#   並把原檔複製到 archive/weekly-notes.bak」

# 3. 非互動驗收
ls -la ~/hermes-lab/outbox/summary-and-todos.md
ls -la ~/hermes-lab/archive/
hermes logs agent -n 30 --since 15m

通過標準：

• summary-and-todos.md 含摘要與 3 條待辦，且與源檔語意一致。
• archive/ 下有備份，可用 diff 對比。
• 日誌中有對應 tool call 記錄；provider 帳單/dashboard 有本次呼叫（便於核對成本）。

回滾：rm ~/hermes-lab/outbox/summary-and-todos.md && cp ~/hermes-lab/archive/weekly-notes.bak ~/hermes-lab/inbox/weekly-notes.txt。失敗先看：模型是否因上下文截斷未讀完檔案 → 權限是否拒絕寫入 outbox → errors.log 中 tool 報錯詳情。

9. 常見問題排查：按層定位，避免盲目重裝

發布前事實核對清單（維護者用）：官方 install.sh URL、最低 macOS、預設目錄名、CLI 子命令、provider 環境變數名、日誌路徑——任一項變更都應先改文件再發布。讀者側只需記住：遇錯先 hermes doctor，再查 errors.log，最後才考慮重裝。

10. 下一步怎麼擴展：從測試目錄到真實 workflow

驗收通過後，建議按下面節奏擴展，不要一步接入生產倉庫或支付系統：

1. 把單個真實 side project 目錄加入白名單，仍禁止 ~/.ssh 與全域 * 讀寫。
2. 啟用 hermes cron 跑每日低風險任務（如整理下載資料夾清單——仍限測試目錄）。
3. 配置一個訊息閘道（Telegram/Discord）並用配對模式限制陌生人（見官方 Security 文件）。
4. 建立 hermes backup --quick 的每週節奏，再讀長期維護文做升級與回滾演練。