說明
疑難排解
常見問題與解決方法。引號中的訊息是 App 實際顯示的文字。
#無法擷取螢幕或視窗（macOS）
訊息：錄製整個螢幕或其他視窗需要 macOS 的螢幕錄製權限。
- 在 錄製目標 對話框中，按 開啟系統設定。
- 在 隱私權與安全性 → 螢幕與系統錄音 中開啟 Ferret。
- 重新啟動 App，然後按 重新檢查。
錄製 內建瀏覽器 不需要任何權限。
在 macOS 上從原始碼執行時，pnpm dev 會啟動一份已改名、經 ad-hoc 簽署且同樣叫做 Ferret 的 Electron 副本（scripts/prepare-dev-electron.mjs），因此它會在這些清單中顯示為另一個 Ferret 項目。第一次執行時，macOS 會再次要求螢幕錄製與麥克風的存取權限，之後就不會再詢問。開發版本使用模擬的鑰匙圈（--use-mock-keychain），所以不會出現鑰匙圈的提示：在開發版本中儲存的 Cookie 與金鑰是以固定的金鑰加密，而非真正的鑰匙圈。設定 ADE_DEV_REAL_KEYCHAIN=1 即可使用真正的鑰匙圈。
#麥克風無法開啟
訊息：無法開啟麥克風。請在作業系統設定中確認權限。
- macOS：在 系統設定 → 隱私權與安全性 → 麥克風 中開啟 Ferret。
- Windows：在 設定 → 隱私權與安全性 → 麥克風 中允許桌面應用程式。
沒有麥克風時，用畫筆圈選仍會產生意見，但不會附帶口述的要求。
#沒有本機模型 / 找不到 whisper-cli
訊息：找不到本機轉錄模型。音訊會儲存，且只會處理畫筆意見。
請在設定中下載模型，或選擇現有的 ggml-*.bin。如果設定中顯示 找不到 whisper.cpp（whisper-cli）
，請安裝它（安裝說明），確認它在 PATH 中，然後重新開啟設定。從 Finder 或檔案總管啟動的打包版 App 可能讀不到你 shell 的 PATH，因此請安裝到 Homebrew 等標準位置。
未通過 sha256 檢查的模型下載會被捨棄，請重試。
#終端機：無法載入 node-pty
從原始碼執行時，如果 node-pty 是針對不同的 Node 或 Electron ABI 建置的，就會發生這種情況。
pnpm rebuild:native#找不到 Agent / 傳送給 Agent 沒有送出
- 終端機中出現
command not found: claude（或codex、gemini等其他 Agent 的指令）：表示 CLI 未安裝或不在PATH中。Ferret 會直接顯示 shell 本身的錯誤，不另外加上提示。請確認該指令在你平常的終端機中可以執行，使用 設定 → Agent 中的 安裝，或將絕對路徑設為該 Agent 的 指令。 Agent 正在等待確認。請在終端機中回應後再傳送。
請先回應 Agent 的提示。Agent 的輸入尚未就緒。
請等 Agent 啟動完成。文字已輸入但尚未送出。請在終端機中按下 Enter。
請先開啟終端機。
無法解析啟動參數：引號未閉合。
請修正 Agent 參數中的引號。
#無法開始錄製
請先開啟專案資料夾。
請先開啟要審查的 URL。
頁面未載入。請開啟可正常顯示的 URL 後再錄製。
請確認開發伺服器正在執行。無法連線到伺服器
表示該連接埠上沒有任何服務在監聽。
#未設定 OpenAI 金鑰或端點
未設定 OpenAI API key…
或 未設定轉錄 endpoint（Base URL / 模型）…
：請在設定中新增，或切換到 本機（免費）。該次錄製的音訊已經儲存。
#GitHub 錯誤
找不到 GitHub CLI（gh）。
請安裝gh。尚未登入 GitHub。
請使用 設定 → GitHub / GitLab → 在終端機中登入。沒有 origin 遠端。
或origin 不是 GitHub 儲存庫。
請檢查git remote -v。找不到儲存庫，或你沒有存取權限。
請檢查gh auth status與GH_TOKEN。
#回報錯誤
請在 github.com/JapanMarketing-Dev/ferret/issues （在新分頁中開啟） 建立 Issue，並附上你的作業系統、App 版本（頁尾 → 更新）以及重現步驟。請勿附上含有私人畫面的 .ferret/ 內容。