2026 Hermes Agent 安裝與配置清單式指南
安裝指南 2026-05-23

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 是目前性價比最高的專用主機——現在即可入手,讓清單裡的每一關都在穩定硬體上通過。

Mac mini M4 · Hermes Agent 專用節點

M4.S 清單驗收首選

10 核 CPU 16GB 記憶體 7×24 靜默
$105.9
/ 月起
立即獲取