Hermes agent 換模型後最常遇到的狀況，通常不是新模型真的比較差，而是不同入口悄悄吃到了不同層級的設定。CLI 可能已經順利切到新 provider，但背景常駐的 Telegram gateway 卻仍掛著舊 session；手動對話測試看起來一切正常，一旦交給 cron 自動排程，又被 process-level 環境變數帶到另一個模型。若沒有先理清這些邊界，團隊很容易把時間耗在反覆調 prompt、換模型或重裝套件上，卻忽略真正問題是模型解析路徑根本不一致。這類問題必須從設定邊界著手，而不是靠盲測碰運氣。
本篇目錄
一、先辨識失敗模式：不是「沒生效」，而是生效範圍不同
在 Hermes agent 的運作中，切換失敗通常有三種典型症狀：
- 改了
config.yaml後，已經開啟的聊天視窗仍沿用啟動時解析的模型。 - 在對話內用
/model切換成功，但關閉重開後又退回預設值。 - 排程或 gateway 讀到系統環境變數
HERMES_MODEL，輸出結果和本機 CLI 測試截然不同。
動手修復前，先列出目前所有的存取入口，包括 CLI、gateway、cron、批次腳本、systemd service 與任何包過一層的 wrapper。為每個入口明確標記預期使用的 provider、model、base_url、工作目錄與啟動身分，這張表會直接決定後續該從哪一層介入調整。如果發現設定完全沒動靜，也可以先檢查介面層級是否直接覆蓋了底層配置。
二、把長期預設值固定在 config.yaml
主要模型、provider 與自訂 endpoint 應統一放在 ~/.hermes/config.yaml；API key、OAuth token 與其他機密憑證則集中放在 ~/.hermes/.env。
需要新增或重新設定 provider 時，用 hermes model 順著走一次設定流程，再用 hermes config show 檢查有效值。若使用自訂 OpenAI-compatible endpoint，model 名稱、provider 與 base_url 要一起核對，不要只改其中一項。調整前先複製一份可隨時還原的 baseline，並記錄原本版本、修改者與目的；這樣新模型表現不如預期時，可以先回到穩定組合，再分項測試差異。
千萬不要為了臨時測試把 HERMES_MODEL 寫進全域 shell rc，因為它會默默影響之後從同一個 shell 啟動的所有程式，讓排查變成漫長的人肉追查。
三、先排除 provider 與認證錯配
模型名稱看起來相同，不代表實際走同一條 API。團隊常見的設定失誤是把 OpenRouter 的模型 ID 貼到自訂 endpoint、把 OpenAI key 配到不相容的 provider，或是在本機 .env 留著舊 key，導致系統 fallback 到另一組帳號。
排查時要把 provider、model、base_url、credential 來源視為一體，不可只改模型字串。若同一台機器有多個 profile，也要確認 HERMES_HOME 是否指向同一個 ~/.hermes；不同 profile 會有各自獨立的 config、.env、session 與 cron 狀態，混在一起最容易造成「我明明改過」的錯覺。
四、臨時切換只留在 session 或單次 process
針對不同情境，設定覆寫應遵循最小範圍原則：
- 如果只要測試某次對話，使用 session 內的
/model provider:model，或 CLI 啟動時的--model。 - 如果只要讓某個排程跑特定模型，才在該 cron wrapper、systemd unit 或腳本內設定
HERMES_MODEL。
原則是覆寫範圍越小越好，並在任務註解清楚「為什麼這裡不同」。例如批次摘要可以指定較便宜的模型，正式回覆仍使用 config.yaml 的預設模型；但不要把 per-run override 當成正式預設，也不要讓 GUI、設定檔與排程環境各自保存一套互相矛盾的模型名稱。不同執行任務的工作目錄與環境設定也必須切換乾淨，避免路徑錯亂。
五、修改後要重啟正確的進程
config.yaml 的變更通常只會套用在「新建立」的 session；gateway、常駐服務或已開啟的對話視窗不會自動熱載入當時解析好的模型。
正確的修正流程應是：
- 保存
config.yaml與.env。 - 重啟 gateway 或對應服務進程。
- 開啟全新 session 進行測試。
若服務由 systemd 管理，要確認 unit 內沒有另外帶入 Environment=HERMES_MODEL；若由 shell script 啟動，要檢查 script 是否載入不同的 .env。只在舊聊天裡看到結果相同，不能判定設定沒生效；只驗 CLI，也不能代表 Telegram 或 cron 已經一致。
六、用固定檢查清單驗證一致性
驗證時跑同一組簡短測試：
- 先執行
hermes doctor排除安裝、PATH 與連線問題。 - 再用
hermes config show確認 provider、model、base_url。 - 分別從 CLI、gateway 與一個測試排程送相同 prompt，記錄實際使用的模型、回應時間與錯誤訊息。
- 若需要臨時覆寫，測完立即移除，並確認下一個新 session 回到
config.yaml的預設值。
最後把本次調整寫進變更紀錄：改了哪個檔案、影響哪個入口、重啟了哪個服務、用哪個 prompt 驗證。若結果仍不一致，先回復上一版 config，再逐項加入變更，不要同時改 provider、模型與 endpoint。
上線前可以用三個條件判定完成：第一，新開 CLI session 顯示預期模型；第二，gateway 重啟後從訊息入口送測試訊息仍使用同一 provider；第三，測試 cron 在沒有多餘環境覆寫時也能讀到同一組設定。三項都通過，才算模型切換完成。若團隊需要多人維護，這三項也要寫進交接文件，避免下一個人只看單一入口就誤判。
把 Hermes 的模型設定收斂成三層：長期預設放 config.yaml，秘密放 .env，臨時需求留在 session 或單次 process。每次調整只動一層、重啟對應入口、再用相同測試驗證，模型切換才會是可維運的操作，而不是每次更新後都重新猜一次。這也是避免成本突然拉高與品質漂移的基本控管方式。
常見問題 FAQ
/model 主要用於當前 session 的切換；hermes model 用來設定 provider、認證與後續新 session 的預設模型。
gateway 是長駐進程，可能仍持有啟動時設定。修改後要重啟 gateway，再開新 session 驗證。
適合單次 process、cron wrapper 或明確的 service 設定；不建議放進全域 shell 環境，避免影響其他入口。
至少驗證 CLI、實際使用的訊息入口與排程入口，並確認三邊讀到同一組 provider、model 與 base_url。