排錯的正確順序

📅 2026年7月23日適用版本 >=2026.5 ✅ 最後驗證 2026年7月4日 ✍️ HermesAgent.download Contributors

出錯時最浪費時間的做法,是看到錯誤訊息就直接搜尋那句話,然後照著網路上找到的解法亂試。

因為 agent 是一條鏈:執行檔 → 設定檔 → 模型連線 → 功能。任何一環斷掉,症狀都可能表現在後面。你以為是模型的問題,其實是設定沒讀到;你以為是設定錯了,其實是根本裝在另一個環境。

所以照順序查。四層,每層都有一個明確的指令可以驗證。

第一層:執行檔存在嗎

hermes doctor

這是官方診斷指令¹。如果連這個指令都找不到,問題在最外層——不是設定、不是模型,是你的 shell 找不到執行檔。

→ command not found 怎麼解(九成是 shell 沒重載 PATH,不是安裝失敗)

環境搞混也很常見:在 WSL2 裝的東西,PowerShell 找不到;在系統 Python 裝的,uv 環境裡找不到。先確認你現在這個 shell 就是你安裝時用的那個。

hermes config show

完成判準:輸出裡看得到供應商與模型,而且是你以為的那個;key 欄位有值。

兩者任一不對,問題就在這一層。

這一層最常見的陷阱是 ~/.hermes/.env 裡有舊的、衝突的設定,蓋掉了你剛設的¹。

hermes

隨便問一句話。這一步會把「設定正確」和「真的能用」分開——設定填對了,但 key 過期、額度用完、模型名稱不存在,都會在這裡才爆出來。

看錯誤訊息的具體內容:提到 key 就回第二層;提到 context 或 token 就是第四層;提到模型名稱不存在,回去確認 HERMES_MODEL 拼字。

前三層都通了,問題就在具體功能上。這時候症狀通常很明確:

如果上面四層都排除了,很可能你遇到的是已知問題。我們整理了 300 多篇官方 GitHub issue 的中文摘要,依元件分類:

每篇都附原始 issue 連結,可以直接去看討論串或追蹤修復進度。

確認不是已知問題,而且你覺得這裡的文件應該要寫但沒寫—— 開一個 issue 告訴我們。你花時間解出來的東西,下一個人就不用再花一次。