2026 Hermes Agent 全網最完整安裝與配置指南:清單式保姆教程加實戰案例
Hermes Agent 教程最怕「看起來很完整,做完沒法驗收」。本文把安裝、配置、首次執行和實戰案例整理成六階段清單——每項都寫明檢查動作、通過標準,以及沒通過時先查哪裡。
你可能已經執行了安裝命令,但 API Key 沒配好;也可能啟動成功了,但權限範圍太大,日誌也不知道在哪裡。完整安裝配置應該按階段驗收:只有環境、安裝、模型、權限、日誌和實戰案例都通過,才算 Hermes Agent 真正可用。
先行結論:官方推薦 macOS 使用一行安裝腳本(僅需預先安裝 Git);配置集中在 ~/.hermes/;健康檢查用 hermes doctor;實戰案例只在專用測試目錄裡跑,不要一上來就給全碟權限。
總清單:從 0 到案例跑通
按順序勾選六個階段。全部打勾後,再考慮接入 Gateway、Cron 或正式程式庫。
| 階段 | 核心驗收 | 關鍵命令/路徑 |
|---|---|---|
| ① 安裝前 | Git、網路、測試目錄、API Key 帳號就緒 | git --version、~/hermes-workspace |
| ② 安裝 | hermes --version 可用,目錄結構正確 |
官方 install.sh、~/.local/bin/hermes |
| ③ 配置 | provider、模型、.env、工作目錄、日誌路徑確認 | hermes setup、~/.hermes/.env |
| ④ 首次執行 | 模型 ping、讀寫測試檔案、日誌寫入、重啟恢復 | hermes、hermes doctor |
| ⑤ 實戰案例 | 摘要+待辦輸出、日誌可追溯、可回滾 | 測試目錄內 sample.txt |
| ⑥ 排錯/收尾 | 分層倒查,權限收斂後再擴 workflow | ~/.hermes/logs/ |
1. 安裝前清單
在複製任何 curl 命令之前,先把下面表格逐項打勾。官方 Git 安裝器唯一硬性前置依賴是 Git;Python 3.11、Node.js v22、uv、ripgrep、ffmpeg 會由安裝腳本自動處理。
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 確認 macOS 與晶片 | Apple Silicon 或 Intel Mac,系統版本滿足目前 官方安裝文件 要求 | 系統升級或改用 pip / Nix 路徑 |
| ☐ | git --version |
能輸出版本號;未安裝則 xcode-select --install 或 Homebrew 安裝 git |
Xcode CLT / Homebrew |
| ☐ | 測試網路 | curl -I https://raw.githubusercontent.com 與所選 LLM provider 網域均可達 |
代理、DNS、公司防火牆 |
| ☐ | 確認磁碟空間 | 至少預留 5–10 GB(含 Python venv、Node、瀏覽器自動化依賴) | 清理 ~/Library/Caches |
| ☐ | 註冊 LLM 帳號並產生 API Key | 推薦 OpenRouter(彈性)或 Anthropic / OpenAI 等;Key 已複製到密碼管理器,未寫入聊天或截圖 | provider 控制台帳單與地區可用性 |
| ☐ | 建立測試工作區 | mkdir -p ~/hermes-workspace/{inbox,outbox,scratch,backups} 且 chmod 700 ~/hermes-workspace |
路徑拼寫、磁碟權限 |
| ☐ | 備份現有配置(若重裝) | 舊 ~/.hermes/ 已 tar 備份到 backups/ |
勿直接 rm -rf ~/.hermes 除非已備份 |
| ☐ | 準備樣本文本(實戰用) | ~/hermes-workspace/inbox/sample.txt 已建立,內容 200–500 字即可 |
檔案編碼 UTF-8 |
2. 安裝清單
macOS 官方推薦命令(2026 年 5 月文件):
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
備選:pip install hermes-agent(PyPI,v0.14+);Nix 使用者請見官方 Nix 指南。自訂安裝目錄可設 HERMES_INSTALL_DIR,詳見官方文件。
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 確認命令來源 | URL 指向 NousResearch/hermes-agent 官方儲存庫 main/scripts/install.sh |
勿使用來路不明的一鍵腳本 |
| ☐ | 觀察安裝輸出 | 無致命 error;出現 clone venv、uv、Node 等步驟且無中斷 | 網路逾時 → 重試;權限 → 勿 sudo 除非明確需要 root 模式 |
| ☐ | source ~/.zshrc 後 which hermes |
路徑為 ~/.local/bin/hermes(per-user 安裝) |
PATH 未刷新 → 重開終端機;檢查 ~/.local/bin 是否在 PATH |
| ☐ | hermes --version 或 hermes doctor |
CLI 正常輸出版本/診斷,無 command not found |
是否誤用系統 Python 調 repo 原始碼而非 venv launcher |
| ☐ | 核對安裝布局 | 程式碼在 ~/.hermes/hermes-agent/,資料目錄 ~/.hermes/ 已建立 |
HERMES_HOME 是否被意外覆蓋 |
| ☐ | 檢查執行時期依賴 | hermes doctor 對 Python、Node、ripgrep 等項為 green / 有修復建議 |
doctor 輸出中的具體缺失項;必要時 hermes update |
3. 配置清單
配置主檔:~/.hermes/config.yaml(主設定)與 ~/.hermes/.env(API Key 與環境變數)。推薦首次執行完整精靈:
hermes setup # 全量精靈
# 或分項:
hermes model # 選擇 provider 與模型
hermes tools # 啟用/停用工具
hermes config set KEY value
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 配置 LLM provider | hermes model 完成後 config.yaml 含 model.default;OpenRouter 範例:OPENROUTER_API_KEY 寫入 .env |
Key 拼寫、provider 地區限制、餘額 |
| ☐ | 密鑰檔案權限 | chmod 600 ~/.hermes/.env;config.yaml 中無明文 key |
是否誤把 key 寫進 yaml 或 git |
| ☐ | 工作目錄 | MESSAGING_CWD=~/hermes-workspace(或絕對路徑)已寫入 .env |
路徑不存在、iCloud 同步目錄誤用 |
| ☐ | 終端機後端與權限 | 試用階段保持 terminal.backend: local + approvals.mode: manual;正式環境再考慮 docker/ssh |
是否誤開 YOLO 或 GATEWAY_ALLOW_ALL_USERS |
| ☐ | 日誌位置 | ~/.hermes/logs/ 存在且可寫;確認不在 Dropbox/iCloud 同步路徑 |
磁碟滿、目錄權限 |
| ☐ | 工具集 | hermes tools 僅啟用案例所需工具(檔案讀寫、終端機);瀏覽器/閘道可後續再加 |
多餘工具導致權限面過大 |
| ☐ | 配置完整性 | hermes config check 通過;升級後必要時 hermes config migrate |
版本跳躍未 migrate |
4. 首次執行清單
cd ~/hermes-workspace
hermes # 進入互動 CLI
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 模型 ping | 傳送「你好,回覆 OK」類短 prompt,數秒內收到合理回覆;無 API key not set |
hermes model、.env 變數名、provider 狀態頁 |
| ☐ | 檔案讀寫 | 讓 agent 在 scratch/ 建立 ping.txt 並讀回;檔案僅出現在工作區內 |
cwd、macOS 隱私權限彈窗、審批是否被誤拒 |
| ☐ | 日誌寫入 | 對話後 ~/.hermes/logs/ 有新條目或時間戳更新 |
日誌層級、目錄權限 |
| ☐ | 關閉終端機再開 | 新終端機中 hermes 仍可啟動,配置未遺失 |
shell profile 未持久化 PATH |
| ☐ | 重啟 Mac 後恢復(可選) | 重啟後 CLI 仍可用;若已 hermes gateway install,launchd 服務按官方文件自啟 |
launchctl list | grep hermes、gateway 日誌 |
| ☐ | hermes doctor 終檢 |
無 blocking 項;安裝方式偵測正確(git / pip / nix) | 按 doctor 逐條修復,勿盲目重裝 |
5. 實戰案例清單:文字摘要 + 待辦提取
在測試目錄完成第一個可驗收任務。不要指向正式程式庫、雲端控制台或 ~/Documents。
5.1 準備輸入
cat > ~/hermes-workspace/inbox/sample.txt <<'EOF'
專案週會紀要(測試樣本)
- 張三:下週完成 API 文件 v2
- 李四:修復登入頁 403 問題,截止週三
- 王五:調研 Hermes Agent 與 OpenClaw 差異,週五匯報
EOF
cp ~/hermes-workspace/inbox/sample.txt ~/hermes-workspace/backups/sample.txt.bak
5.2 任務 prompt(複製到 hermes CLI)
請讀取 inbox/sample.txt,在 outbox/ 產生兩份檔案:
1) summary.md — 200 字以內摘要
2) todos.md — Markdown 待辦清單,每項含負責人與截止日期
不要修改 inbox 原檔案,不要存取工作區以外的路徑。
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 輸出檔案存在 | outbox/summary.md 與 outbox/todos.md 已產生,內容與人名/日期匹配 |
審批是否 pending、模型是否幻覺編造 |
| ☐ | 原檔案未變 | diff inbox/sample.txt backups/sample.txt.bak 無差異 |
prompt 約束、工具權限 |
| ☐ | 日誌可追溯 | 日誌中有本次 session 的工具呼叫記錄 | 日誌路徑、日誌層級 |
| ☐ | 回滾驗證 | rm outbox/*.md 後可重新跑任務並成功;backup 仍可恢復 |
工作階段快取、檔案鎖 |
| ☐ | 成本觀察 | provider 控制台可見本次 token 用量在預期內;已設 spend limit(若 provider 支援) | 模型是否過大、是否陷入 tool 迴圈 |
| ☐ | 權限邊界 | agent 未嘗試讀 ~/.hermes/.env 或 ~/.ssh;危險命令觸發 manual 審批 |
tools 配置、審批模式 |
6. 排錯清單:分層倒查,別先重裝
遇到問題時按層向下查,每層通過再進下一層。多數「裝完不能用」是 PATH、Key 或 cwd,不是 Hermes 本體損壞。
| 層級 | 症狀 | 先查 | 常見修復 |
|---|---|---|---|
| 依賴 | hermes: command not found |
PATH、~/.local/bin |
source ~/.zshrc |
| 網路 | 安裝/模型逾時 | curl GitHub、provider API | 代理、DNS、換網路 |
| Key | API key not set |
~/.hermes/.env 變數名 |
hermes model 或 hermes config set |
| Provider | 401/429/5xx | provider 狀態頁、餘額、模型 ID | 換模型、設限額、稍後重試 |
| 權限 | 無法寫檔案 / 命令被拒 | cwd、審批佇列、macOS TCC | 批准命令、縮小/修正工作目錄 |
| 路徑 | 找不到 config | HERMES_HOME、多使用者衝突 |
統一 HERMES_HOME 或專用帳戶 |
| 日誌 | 靜默失敗 | ~/.hermes/logs/、errors.log |
按日誌關鍵字定向修配置 |
| 背景服務 | Gateway 不回應 | launchd 狀態、token、白名單 | hermes gateway 子命令、官方 gateway 文件 |
7. 完成後清單:接入真實 workflow 之前
- ☐ 再次備份
~/.hermes/(含 config、skills、非密鑰工作階段若需要) - ☐ 確認
approvals.mode仍為 manual 或符合團隊策略 - ☐ Gateway 若啟用:白名單 / DM pairing 已配置,未使用
GATEWAY_ALLOW_ALL_USERS - ☐ 在 provider 控制台設定 spend limit 與告警
- ☐ 人工抽查 outbox 輸出品質,再決定是否綁定真實 repo
- ☐ 閱讀官方 Security 文件,再擴大工具集或 terminal 後端
全部階段驗收通過後,再擴展 Telegram Gateway、Cron 定時任務或 CI 整合。若需進一步收緊 Mac 上的權限與密鑰邊界,可參考本站同主題的Hermes Agent Mac 安全配置指南。
在 Mac mini 上跑通 Hermes,驗收更省心
Hermes Agent 依賴 Git、Python、Node 和 Unix 終端機工具鏈——這些在 macOS 上原生可用,無需 WSL 或額外驅動。把 agent 放在專用 Mac mini 上,可以把 CLI 試用、Gateway 和日誌與主力 MacBook 的個人檔案隔離;Apple Silicon 統一記憶體對本地 Ollama 等輔助路由更友善,macOS 的 Gatekeeper、SIP 與 FileVault 也提供系統級完整性保護。
Mac mini M4 待機功耗約 4W、無風扇靜音,適合作為 7×24 的 agent 節點;配合 hermes gateway install 的 launchd 守護,重啟後服務可自動恢復。若你正按本文清單驗收 Hermes,Mac mini M4 是目前性價比最高的專用主機——現在即可入手,讓清單裡的每一關都在穩定硬體上通過。