🚑 疑難排解
依症狀分類的問題排除，對應上游 GitHub issues
排程沒跑？先查 gateway、jobs.json 和 output，不要只看 Desktop 畫面
Hermes cron 的執行者是 gateway daemon，不是你眼前那個聊天視窗。這篇用一個 macOS 週二自動任務的實測案例，教你分辨：排程沒觸發、任務有跑但腳本失敗、任務成功但沒有傳訊息。
hermes doctor 到底檢查什麼：16 個區塊逐項解讀
附 macOS 實機輸出。教你分辨 ⚠ 是「壞掉」還是「你沒裝而已」，並提醒兩件官方沒講的事：離開代碼永遠是 0，以及 hermes status --all 在舊版會把 API 金鑰完整印出來。
Hermes 越用越慢：看到 Preflight compression 時該怎麼辦
長 session 會讓每輪輸入膨脹，Hermes 進入 preflight compression 後，體感可能從幾秒變成幾十秒。這篇用 macOS v0.17.0 實測 log 說明怎麼判斷、急救與預防。
macOS 語音轉文字沒有產出 transcript：Homebrew whisper 找不到 ffmpeg 的解法
桌面版或 gateway 啟動時 PATH 太乾淨，Homebrew whisper 可能跑完但沒有 .txt。這篇用 macOS v0.17.0 實機設定，示範改成 stt.providers 的 command provider，明確把 /opt/homebrew/bin 加進 PATH。
輸入 plan 後 Broken pipe：不是 plan 壞了，是長需求加 skill 把首包拖到逾時
macOS v0.17.0 實機案例：長需求一開始就觸發 plan skill，下一次請求 context 膨脹到約 1.9 萬 token，openai-codex 90 秒沒有首包後被 Hermes 主動斷線。教你怎麼救、怎麼避免。
看到 HTTP 429 錯誤?那是供應商在限你的速度,不是 Hermes 壞了
429 的意思是:提供 AI 模型的公司覺得你送太快了,先擋你一下。這不是 Hermes 出問題。Hermes 會自己重試、再自動換備援,但如果對方一直擋,你就得換做法:掛好幾把鑰匙輪流用、升級方案、或換一家供應商。文章附 Gemini、z.ai 的真實例子。
看到「API key not set」或說 key 無效?這樣一步步查
最常見的原因其實不是 key 打錯,而是 key 跟供應商配錯對了。跟著三步驟慢慢查,包含最容易漏掉的 ~/.hermes/.env 衝突設定。
打 hermes 卻說「找不到指令」?別急,三十秒解決
裝完 Hermes,一打 hermes 卻跳出「找不到指令」?十次有九次不是裝壞了,只是你這個視窗還沒「重新讀」一次設定。跟著做,三十秒就好。
看到 context length exceeded 怎麼辦
對話突然卡住、跳出 context length exceeded?先用一個指令救回現在的對話,再改設定檔一勞永逸。用本地模型的人特別容易遇到,原因跟你想的不一樣。
出錯了?照這個順序查,不會白費力氣
看到錯誤就上網搜那句話、亂試網路上的解法,最浪費時間。這篇教你一個固定順序:先看程式在不在、再看設定對不對、再看模型連不連得上、最後才查功能。一層一層來,每層都有一句指令幫你確認。
看到「Hermes requires Python 3.11 or newer」怎麼辦
這行錯誤通常代表你沒用官方的安裝方式。這裡有三種修法,還會告訴你為什麼有些人不會遇到。
Telegram 接 Hermes Agent 常遇到的兩個問題
指令選單裡少了幾個功能、gateway(讓 bot 收發訊息的那一層)跑一跑自己斷線:這兩件事都不是你設錯,有原因也有解法。