正如許多開發者在維護 Hermes agent 時會發現的，大家在公開討論區裡最常抱怨的一個痛點就是：「組態優先級混亂 (Config Precedence Nightmare)」。明明已經手動修改了 config.yaml 裡的 model 設定，怎麼實際執行時，Agent 還是固執地讀取舊的、或者是錯誤的模型代號？
這種問題通常不是模型名稱打錯那種低級錯誤，而是來自於多個不同的組態來源混雜在一起：GUI 介面、本機 config file、環境變數、甚至是容器啟動時的 argv 參數。這導致最後誰「覆蓋（override）」誰根本不清楚。
本篇目錄
Hermes Agent 組態管理：為什麼我的 Model 設定沒生效？
在開發者公開討論區裡，我們常看到一個容易被忽略但極其煩人的常見陷阱 (Common Pitfalls)：「我明明改了設定檔，怎麼實際行為還是舊的？」這通常不是模型名稱打錯，而是組態優先級混亂 (Config Precedence Nightmare)。
這不是因為選擇器壞了，而是因為開發者沒有理清楚當前環境下誰才是唯一真相。
陷阱一：GUI 的隱形控制權（Overriding State）
社群裡最容易踩的坑，就是以為改了 .yaml 檔就等於改了實際行為。很多 Agent 類工具（如市面上的 UI 封裝版或工具鏈介面）都會提供一層 GUI 設定介面，讓使用者快速重新選擇模型、工具或行為模式。
問題在於：GUI 不是只做展示，它擁有更高的 precedence（優先級）。 當 GUI 啟動並載入其內部狀態（例如儲存在 SQLite 或本機快存中）時，它會直接在 runtime（執行期）覆蓋你在 config.yaml 裡寫入的設定。結果就是你以為改好了，實際跑的還是 GUI 內存的舊值。
陷阱二：不同進入點導致的讀取偏差（Entry Point Drifts）
另一個常見來源是不同啟動方式（Startup Modes）。我們可能在桌面端 GUI 版驗證流程、在 CLI 裡除錯、又或者在 Docker 容器或 K8s 배경服務裡正式部署。只要啟動模式（也是 Entry Point）變了，Hermes Agent 就可能把「同一份設定」解讀成不同結果。
- 桌面版： 可能優先讀取隱藏的 persistent state。
- CLI： 可能顯式讀取
--config=~/.hermes/config.yaml。 - Docker： 可能完全依賴容器注入的環境變數。
如果你沒有統一設定檔的路徑或將組態當成唯一真相，久了就會出現「檔案裡看起來對，但跑起來不對」的狀況。這時候最有效的不是再多改一個地方，而是縮小來源數量：只保留一個主設定來源，把 GUI 當覆蓋層或乾脆關掉介面功能。
開發者 SOP：組態管理實務檢查順序
要徹底除錯組態衝突，我們建議建立一個實務 SOP，檢查順序如下：
- 先查 Entry Point flags： 實地檢查實際的啟動命令。終端機 argv 參數通常具有最高優先級。
- 再看 GUI Precedence： 確認 GUI 是否覆蓋了同名欄位。如果 Agent 偵測到 GUI 狀態，config file 通常會變成備援方案。
- 確認本機 Config 路徑： 實地確認 Agent 目前到底是從讀取哪一個
.yaml檔案路徑。許多「版本漂移（version drift）」問題都來自於 Agent 預設讀取了過時的預設檔。
只要這三層沒對齊，後面再怎麼在 config.yaml 調 model，都只是做表面功夫。
常見問題 (FAQ)
最常見的是GUI 設定優先級更高，或者是你改錯了 Entry Point 讀取的來源。
可以先比對實地啟動參數，再交叉比對 GUI 和 .yaml 檔案裡的同名欄位。有些 agent 提供了 --debug --print-config 命令，可以輸出實際生效的組態。
實踐「唯一真相（Single Source of Truth）」策略。將組態管理放在環境變數（適合容器化）或單一的 .yaml 設定檔上，將其他來源（如 GUI）僅作為覆蓋層，不要讓多個來源同時爭搶設定控制權。