2026 Hermes Agent 全網最完整
安裝與配置指南：用一個實戰案例跑通保姆教程
只裝 Hermes Agent 不跑案例，你很難判斷它到底可不可用。本文先定一個低風險文件處理實戰案例，再按「環境 → 安裝 → 配置 → 驗收 → 執行 → 排錯」走完 2026 年 Mac 版完整安裝與配置保姆教程：在獨立測試目錄裡讀樣本文本、生成摘要與待辦、寫出結果檔案，並在 ~/.hermes/logs/ 裡核對全過程。（核對至 2026-05-23；模型名稱與價格以各 provider 官網為準。）
啟動成功只是第一步。真正關鍵的是：模型能否調用、檔案能否按邊界讀寫、日誌能否追蹤、失敗後能否定位。案例不是另寫一篇 workflow 專題，而是用來證明安裝與配置真的可用——通過後再擴展到真實 Hermes Agent workflow。
一先定義要跑通的實戰案例
第一個案例必須低風險、可回滾、可驗證，不要一上來就接生產倉庫或隱私目錄。
| 要素 | 本教程固定方案 | 通過標準 |
|---|---|---|
| 測試目錄 | ~/hermes-lab/（可隨時 rm -rf 刪除） |
Agent 只在此目錄讀寫 |
| 輸入 | input/notes.md（自擬 3～5 段會議筆記） |
CLI 能讀取全文 |
| 輸出 | output/summary.md + output/todos.md |
兩個檔案存在且內容合理 |
| 日誌 | ~/.hermes/logs/ |
能看到模型調用與工具軌跡 |
| 回滾 | 刪除 ~/hermes-lab/output/* |
重跑案例結果一致 |
在終端機建立骨架（驗收前執行一次）：
# 編輯 ~/hermes-lab/input/notes.md，寫入幾段測試文字
二為案例準備安裝環境
- →硬體：Apple Silicon 或 Intel Mac，建議 ≥16GB 記憶體、≥5GB 可用磁碟；
uname -m、sw_vers確認晶片與系統。 - →依賴：僅需
git --version；Python 3.11、Node v22、ripgrep、ffmpeg 由官方安裝器自動處理。 - →網路：能訪問 GitHub raw 與你選的 LLM API 端點（如 OpenRouter、Anthropic）。
- →帳號：至少一個 provider 的 API Key；密鑰只放
~/.hermes/.env，並chmod 600。 - →權限：本機管理員帳號；首次使用檔案/終端機工具時按需處理 macOS 隱私彈窗。
--yolo 或 approvals.mode: off。
三安裝 Hermes Agent 並確認版本
然後 source ~/.zshrc，按官方流程跑 hermes setup 或 hermes model。安裝後必查：
- ✓
which hermes→ 通常~/.local/bin/hermes - ✓
hermes doctor無阻塞項（缺 Key 會提示配置模型） - ✓
hermes update了解當前版本；代碼在~/.hermes/hermes-agent/，數據在~/.hermes/
未通過 hermes doctor 不要進入配置案例步驟。
四為案例配置模型與 API Key
運行 hermes model 選擇 provider 與預設模型（名稱與計費以官網實時為準）。也可寫入 ~/.hermes/.env，例如：
OPENROUTER_API_KEY=sk-or-...
chmod 600 ~/.hermes/.env
連通性驗收：在 ~/hermes-lab 下啟動 hermes，發一句「回覆 OK」；若 API 報錯，先跑 hermes config check，不要繼續案例。
五為案例設置目錄與權限邊界
首次驗證建議在測試目錄內操作：執行案例前先 cd ~/hermes-lab 再啟動 hermes。若後續用 Messaging Gateway，可在 ~/.hermes/.env 設置 MESSAGING_CWD=~/hermes-lab，避免 Agent 從敏感路徑起步（見官方安全文件）。
- →保持
approvals.mode: manual（預設），危險命令需人工批准。 - →進階隔離：在
~/.hermes/config.yaml設terminal.backend: docker，把容器當安全邊界（生產 Gateway 推薦）。 - →勿把 API Key 寫進
~/hermes-lab內任何會被 Git 追蹤的檔案。
六首次運行前驗收（分步閘門）
- ①模型 ping：對話能收到正常回覆
- ②讀檔案：讓 Agent 總結
input/notes.md第一段 - ③寫檔案：在
output/生成ping.txt，內容為ok - ④看日誌：
ls ~/.hermes/logs/，CLI 會話相關記錄應可追蹤
任一步失敗，先停在當前層排錯，不要跑完整案例。
七執行完整實戰案例
在 ~/hermes-lab 啟動 hermes，用清晰任務描述（可複製調整）：
input/notes.md，在 output/summary.md 寫 200 字以內中文摘要，在 output/todos.md 列出最多 5 條可執行待辦（Markdown 列表）。不要訪問本目錄以外的路徑，不要執行破壞性 shell 命令。
執行中若出現刪除、改系統配置等危險命令，應在 CLI 批准提示處拒絕——這正是配置生效的證明。
八驗收、排錯與可回滾檢查
| 檢查項 | 命令 / 位置 |
|---|---|
| 輸出檔案 | cat ~/hermes-lab/output/summary.md、todos.md |
| 權限越界 | 確認 ~/、桌面等無意外新檔案 |
| 日誌 | ~/.hermes/logs/（Gateway 常用 gateway.log） |
| 費用 | provider 控制檯查看本次 token 消耗 |
| 回滾 | rm -rf ~/hermes-lab/output/* 後重跑 |
失敗分層反推：
- →
hermes: command not found→ 安裝層：PATH、source ~/.zshrc - →401 / 模型無響應 → 模型層：
hermes model、.env權限 - →讀不到檔案 / 寫到別處 → 權限層：當前工作目錄、
MESSAGING_CWD、macOS 隱私授權 - →
hermes doctor報配置項 → 配置層：hermes config migrate - →工具一直循環或理解偏題 → 任務層：縮短提示、限定輸出路徑
九從測試案例擴展到真實 workflow
案例跑通後，再按階梯放大權限與自動化，而不是跳過驗證直接上生產：
- 1只讀真實資料目錄，輸出仍寫到獨立
draft/ - 2配置
hermes gateway setup+gateway install，用 launchd 常駐（plist 通常在~/Library/LaunchAgents/ai.hermes.gateway.plist） - 3需要更高自動化時，再評估 Docker 後端、命令白名單與平臺用戶 allowlist
更完整的安裝前清單可參考本站同主題的Hermes Agent Mac 安裝清單。
十在 Mac mini 上跑通案例更省心
本文的安裝、配置與日誌驗收流程，在 macOS 上可原生完成：終端機、Homebrew、Docker 與 launchd 無需 WSL。Mac mini M4 約 4W 級待機功耗、Apple Silicon 統一記憶體，適合作為長期跑 Hermes CLI 與 Gateway 的靜默節點；Gatekeeper 與 FileVault 也降低 Agent 長期在線時的暴露面。
若你正把本教程的測試案例升級為 7×24 workflow，Mac mini M4 是目前性價比很高的硬體起點——現在即可入手，讓安裝配置真正落在為長期運行設計的機器上。
- ①定案例目錄與輸出標準
- ②官方安裝 +
hermes doctor - ③模型 Key + 測試目錄邊界
- ④分步驗收 → 完整案例 → 日誌與回滾
- ⑤再擴展 Gateway 與真實 workflow