疑難排解#
以下問題與解法都是從反編譯原碼推出來的常見卡點 [反編譯]；實際排除效果需人工實測確認。安全與隱私相關疑問請看專頁。
Verity 不回話 / 聊天顯示「Problem setting up AI?」#
錯誤路徑 [反編譯]；需人工實測。
最常見原因：沒有 API 金鑰，或後端連不上。 當 AI 呼叫失敗，模組會在聊天欄丟出「Problem setting up AI? Watch these tutorials.」並附兩支教學影片連結，然後回一句中性的 fallback 訊息。
- 走雲端：確認
apiKey有填、aiProvider正確（GROQ／OPENROUTER）。 - 走本機：確認
use_ollama = true且你真的有把本機 LLM 服務（127.0.0.1:4000）跑起來。 - 改完設定記得重啟遊戲。
有字幕但沒有聲音（TTS）#
TTS 路徑與錯誤 [反編譯]；需人工實測。
- 先確認總開關
useTTS = true。 - 出現紅字「You ran out of TTS tokens! Try switching to Native TTS.」＝雲端語音額度用完 → 把
useNativeTts設true（用系統朗讀器），或改useLocalTts = true（本機 Piper）。 - 日誌出現「Failed to initialize local AI engine」＝本機 TTS 模型沒解壓成功 → 檢查磁碟空間與
config/verity/權限。 - 用 OpenRouter 當後端時不支援雲端 TTS，聊天會提示你切成 Native／本機 TTS。
麥克風沒反應 / 選錯裝置#
麥克風流程 [反編譯]；需人工實測。
- Verity 沒有麥克風選單——按 M 輪替裝置，聊天欄會顯示目前選到哪支。
- 聊天欄出現「No compatible microphones found on this system.」＝系統沒偵測到可用麥克風 → 檢查作業系統的麥克風權限與接線。
- 日誌出現「Microphone not supported / Failed to open microphone line」＝選到的裝置打不開 → 按 M 換一個。
- 記得是按住 V 講話、放開才送出。若你只說了一句「thank you.」它會被當成雜訊丟掉（Whisper 常見的幻聽，模組刻意過濾）。
本機服務連不上（4000 / 8880 / 9000）#
本機端點 [反編譯]；需人工實測。
走離線路線時，這三個服務要分別自己啟動：
| 服務 | 預設端點 | 對應設定 |
|---|---|---|
| 本機 LLM（大腦） | 127.0.0.1:4000 |
use_ollama |
| 本機 TTS（嘴巴） | 127.0.0.1:8880 |
use_kokoro |
| 外部 Whisper（耳朵） | 127.0.0.1:9000 |
use_local_whisper |
連不上時日誌會出現「Failed to process speech upload stream」「Is Groq unreachable?」之類訊息。注意：useLocalStt = true 用的是模組內建的 sherpa Whisper，不需要另外開 9000 服務——首次用麥時它會先初始化（聊天顯示「Initializing Sherpa engine...」），該次可能沒有輸出，屬正常。
惡魔太可怕，我想關掉 / 找回好 Verity#
恢復手段 [反編譯]；需人工實測。
- 當下救急：站在 Verity 10 格內、看它一眼，打字
i came back for you（一次即平息），或i'm sorry連打 3 次。 - 反抗：直接殺死惡魔（400 血），karma 會歸 20、變回開心。
- 管理員：
/changekarma 20（需 OP 權限 2）。 - 一勞永逸：把難度設和平（Peaceful）（不會惡魔化）、或把
dayCount設很大、canCrash = false（不被踢）、killVillagers = false（保村民）。
其他#
其他行為 [反編譯]；需人工實測。
- 晚上睡不著：附近有惡魔時無法睡覺，屬設計。
- 本體不見了：世界裡沒有 Verity 時可用
/recoververity召回，但有 1 小時冷卻。 - 金鑰安全：
apiKey明文存在config/verity-client.toml，分享檔案／截圖前先移除。 - 多人伺服器：AI 對話在伺服器端用主機的金鑰跑，全服聊天都會送出且玩家端無提示；想收斂設
requireVerity = true。
⚠️ 專用伺服器：AI 出錯時「安靜地失敗」#
已反編譯確認 [反編譯]。
AiAPI.askGroq() 的錯誤處理會呼叫 Minecraft.getInstance().player（AiAPI.java:244、329、342），但 Minecraft 是客戶端專屬類別，專用伺服器（dedicated server）的 jar 裡沒有這個類別。
聊天觸發路徑是 ServerChatEvent（伺服器端）→ CompletableFuture.supplyAsync(askGroq)（ModEvents.java:876），所以只要 AI 呼叫失敗（沒填金鑰、金鑰錯、額度用完、網路不通、回應格式壞），就會在那個非同步工作裡丟 NoClassDefFoundError。
實際症狀：伺服器不會崩（例外被 CompletableFuture 吞掉），但——
- 玩家完全收不到模組原本要顯示的「Problem setting up AI?」提示
- 表現就是 Verity 突然不理人，看起來像壞了
怎麼確認：去翻伺服器 log找 [Verity AI] API Error:——這行 System.err 印在觸碰 Minecraft 之前，所以一定看得到，而且會帶出真正的錯誤訊息。
建議：專用伺服器上先在單機／LAN 把金鑰或本機服務設定確認可用，再搬上去；出問題一律以伺服器 log 為準，別等遊戲內提示。
本頁解法皆由反編譯原碼推得 [反編譯]；實際排除效果尚未實機驗證，屬 需人工實測（怎麼確認：重現該情境 → 套用解法 → 觀察是否恢復）。