整套系統由三者組成：Hermes Agent 是 runtime 與狀態層，Gemini 是推論端點，MCP 是工具介接的協定。以下說明為什麼這樣切、怎麼裝起來、組態檔各自管什麼，最後是一個實際卡住的路徑問題。
| 名稱 | 負責什麼 | 交給誰 |
|---|---|---|
| Hermes Agent | 狀態保存、身分宣告、排程、平台介接 | 推論交給 Gemini |
| Gemini | 推論與函式呼叫的判斷 | 狀態保存交給 Hermes |
| MCP | 工具的列舉與呼叫格式 | 工具實作交給各個 server |
在 Agent = Model + Harness 這個等式裡，Gemini 是 Model，Hermes 與 MCP 構成 Harness。
這樣切之後，換掉其中一項要動的範圍是固定的：
config.yaml 的 model: 區段，記憶、SOUL.md、排程與已註冊的工具維持原狀這三件事寫成一支 Python 程式也能跑，呼叫 Gemini、呼叫環控 API、把對話存進資料庫全塞在同一個檔案裡，第一版反而更快做出來。差別出現在要換掉其中一項的時候。
| 寫成一支程式 | 分層 | |
|---|---|---|
| 換推論端點 | 呼叫模型的程式碼散在各處，逐處修改 | 改 provider 組態，其餘各層維持原狀 |
| 換工具 | 工具邏輯與 agent 邏輯寫在一起，得一併重寫 | 工具跑在另一個行程，換掉時 agent 照常運作 |
| 工具出錯 | 可能整支程式停掉 | 影響範圍限於那組工具 |
| 初期速度 | 快，介面可以之後再定 | 慢，得先定義各層的邊界 |
分層得先把介面做出來。環控那組工具要獨立成一個 MCP server，需要：
/health 讓外面知道它還活著寫成一支程式時，在函式裡直接發 HTTP 請求就會動。
這些做完之後，換推論端點時動到的只有
config.yaml的model:區段，工具那一側沿用原檔
兩個名字都來自 Nous Research，一個是 agent runtime，一個是大型語言模型。
| 名稱 | 是什麼 | 官方描述 |
|---|---|---|
| Hermes Agent | agent runtime | 由 Nous Research 打造、能自我改進的 AI agent |
| Hermes 4 | 大型語言模型 | 基於 Llama-3.1 的前沿混合模式推理模型 |
在等式裡，Hermes Agent 屬於 Harness，Hermes 4 屬於 Model。這套組態用的是前者，推論交給 Gemini。
兩者的資料放在不同地方：
NousResearch/hermes-agent
搜到的頁面在講 context 長度與量化格式就是模型，在講 hermes doctor 與 config.yaml 就是 runtime。
安裝程式會一併處理相依套件，準備工作全部由它代勞：
%LOCALAPPDATA%\hermes\git
Windows 原生環境開 PowerShell 執行，以一般使用者權限即可：
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
macOS、Linux、WSL2 與 Termux 執行：
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
裝完把終端機關掉重開。 安裝程式改了 PATH，新視窗才會帶到更新後的路徑。
重開之後跑這兩行驗證：
hermes --version
hermes doctor
hermes doctor 的輸出分十幾個區塊：
最後列出待處理項目，並提示 hermes doctor --fix。
紅字要處理，黃字先看是哪一種。多數黃字代表該項尚未設定，例如 DISCORD_BOT_TOKEN 留空時 discord 那組工具就標黃，用得到時再填。
設定根目錄在 Linux 與 macOS 是 ~/.hermes，Windows 原生安裝是 %LOCALAPPDATA%\hermes。底下的結構：
| 路徑 | 管什麼 |
|---|---|
config.yaml |
模型、工具、外掛啟用清單 |
.env |
API 金鑰與平台 token |
SOUL.md |
身分宣告 |
memories/ |
跨 session 保存的狀態 |
skills/ |
技能 |
plugins/ |
Python 撰寫的 runtime 擴充 |
cron/jobs.json |
排程定義 |
profiles/ |
各 profile 的獨立設定 |
hermes-agent/ |
程式本身的原始碼 |
設定值的生效順序，由高到低：
hermes_cli/config.py 的註解寫明這一層是刻意反轉平常的順序gateway/config.py 的解析順序是 env > config > defaultconfig.yaml：值裡的 ${VAR} 會先用環境變數展開，寫在 .env 的密鑰是流進這一層，而非排在它後面hermes_cli/config_defaults.py
hermes config set 會自動分流，判定為密鑰的寫進 .env，其餘寫進 config.yaml，分流由它判定。
手動改組態檔之前先複製一份 .bak，檔名帶上日期與這次改了什麼，例如 config.yaml.bak.20260905_gateway-fix。
YAML 少一個空格之後，程式會換一種方式繼續跑。hermes_cli/config.py 裡對解析失敗有三種處置：
| 處置 | 行為 |
|---|---|
| 退回預設組態 | 輔助 provider、fallback chain、模型設定這些使用者覆寫全部被忽略 |
| 沿用上一次成功載入的組態 | 該行程繼續跑舊設定，對 config.yaml 的修改被忽略 |
| 拒絕寫入 | 保留現有的 config.yaml |
三種都會把壞掉的那份快照成 config.yaml.corrupt.<時間戳>.bak，並往 stderr 寫一行以 hermes config: 開頭的警告。
它保存的是壞掉的那一份，最後一份能用的組態要自己備份
| 段落 | 內容 |
|---|---|
| 現象 | 依文件在 ~/.hermes/config.yaml 改模型設定，重啟後仍走舊設定，過程靜默 |
| 根本原因 | README 把 HERMES_HOME 的預設值寫成 ~/.hermes，Windows 原生安裝實際落在 %LOCALAPPDATA%\hermes。該機器的 ~/.hermes 底下只有 logs 與 skills 兩個目錄，改的那個 config.yaml 是自己新建的，位在讀取路徑之外 |
| 修正方式 | 改 %LOCALAPPDATA%\hermes\config.yaml |
| 迴歸測試 | 每次改完用 hermes config get 讀回同一個鍵，讀到的值與寫入值一致才代表位置正確 |
靜默是這個問題最花時間的地方。寫進讀取路徑以外的檔案，效果等同於空操作。
文件寫的是預設值，實際值由安裝方式決定。 hermes doctor 的組態檔區塊會印出它實際讀的是哪一個檔案的絕對路徑，動手改之前先跑一次，比對照文件可靠。
設定根目錄底下有一個 hermes-agent 子目錄，那是程式本身的原始碼，node_modules 與 venv 都在裡面。
第一次要備份設定時直接複製整個根目錄，複製視窗的進度條跑了很久才發現在搬的是幾萬個相依套件的檔案。真正需要備份的只有 config.yaml、.env、SOUL.md、cron/jobs.json 與 memories，加起來是幾百 KB 的量級。
設定與程式放在同一個根目錄下，移機時整包搬走確實方便，代價是備份與版本控制都得自己挑檔案。
Profile 機制的隔離邊界，以及檔案系統沙箱的實際歸屬。
iThome鐵人賽
看影片追技術