Risoluzione dei problemi

#La cattura dello schermo o della finestra non funziona (macOS)

Messaggio: Per registrare l'intero schermo o un'altra finestra serve il permesso Registrazione schermo di macOS.

1. Nella finestra Target di registrazione, fai clic su Apri Impostazioni di Sistema.
2. Privacy e sicurezza → Registrazione schermo e audio di sistema: attiva Ferret.
3. Riavvia l'app, poi fai clic su Controlla di nuovo.

Registrare il Browser integrato non richiede alcun permesso.

Quando lo esegui dai sorgenti su macOS, pnpm dev avvia una copia rinominata di Electron, con firma ad hoc, che si chiama anch'essa Ferret (scripts/prepare-dev-electron.mjs), quindi compare come voce Ferret separata in questi elenchi. Al primo avvio macOS chiede di nuovo l'accesso a Registrazione schermo e Microfono. Dopo non lo chiede più. Le build di sviluppo usano un portachiavi fittizio (--use-mock-keychain), quindi non compare alcuna richiesta del Portachiavi: cookie e chiavi salvati in una build di sviluppo sono cifrati con una chiave fissa, non con il vero Portachiavi. Imposta ADE_DEV_REAL_KEYCHAIN=1 per usare il vero Portachiavi.

#Il microfono non si apre

Messaggio: Impossibile aprire il microfono. Controlla il permesso nelle impostazioni del sistema operativo.

• macOS: Impostazioni di Sistema → Privacy e sicurezza → Microfono, poi attiva Ferret.
• Windows: Impostazioni → Privacy e sicurezza → Microfono, poi consenti l'accesso alle app desktop.

Senza microfono, i cerchi della penna creano comunque segnalazioni, ma senza una richiesta a voce.

#Nessun modello sul dispositivo / whisper-cli non trovato

Messaggio: Nessun modello di trascrizione sul dispositivo trovato. L'audio verrà salvato e verranno elaborate solo le segnalazioni con la penna.

Scarica un modello nelle Impostazioni, oppure scegli un ggml-*.bin esistente. Se le Impostazioni dicono whisper.cpp (whisper-cli) non trovato, installalo (istruzioni), assicurati che sia nel PATH e riapri le Impostazioni. Le app pacchettizzate avviate dal Finder o da Esplora file potrebbero non vedere il PATH della tua shell, quindi installalo in un percorso standard come quello di Homebrew.

Un modello scaricato che non supera il controllo sha256 viene scartato. Riprova a scaricarlo.

#Terminale: non è stato possibile caricare node-pty

Succede quando esegui dai sorgenti e node-pty è stato compilato per un ABI di Node o Electron diverso.

pnpm rebuild:native

#Agent non trovato / Invia all'Agent non invia

• command not found: claude (oppure codex, gemini o il comando di un altro agent) nel terminale: la CLI non è installata o non è nel PATH. Ferret mostra l'errore della shell così com'è e non aggiunge suggerimenti. Controlla che il comando funzioni nel tuo terminale abituale, usa Installa in Impostazioni → Agent, oppure imposta un percorso assoluto come Comando di quell'agent.
• L'agent è in attesa di conferma. Rispondi nel terminale, poi invia. Rispondi prima alla richiesta dell'agent.
• L'input dell'agent non è ancora pronto. Attendi che l'agent finisca di avviarsi.
• Il testo è stato inserito ma non inviato. Premi Invio nel terminale.
• Apri prima un terminale.
• Impossibile analizzare gli argomenti di avvio: Virgolette non chiuse. Correggi le virgolette negli argomenti dell'agent.

#La registrazione non si avvia

• Apri prima una cartella di progetto.
• Apri prima un URL da revisionare.
• La pagina non si è caricata. Apri un URL che viene visualizzato, poi registra. Controlla che il server di sviluppo sia in esecuzione. Impossibile connettersi al server significa che nessuno è in ascolto su quella porta.

#Chiave OpenAI o endpoint non impostati

Nessuna chiave API OpenAI impostata… oppure L'endpoint di trascrizione (Base URL / modello) non è impostato…: aggiungili nelle Impostazioni, oppure passa a Sul dispositivo (gratuito). L'audio di quella registrazione è già salvato.

#Errori di GitHub

• GitHub CLI (gh) non trovata. Installa gh.
• Accesso a GitHub non effettuato. Impostazioni → GitHub / GitLab → Accedi nel terminale.
• Nessun remote origin. oppure origin non è un repository GitHub. Controlla git remote -v.
• Repository non trovato oppure non hai accesso. Controlla gh auth status e GH_TOKEN.

#Segnalare un bug

Apri una issue su github.com/JapanMarketing-Dev/ferret/issues (si apre in una nuova scheda) indicando il sistema operativo, la versione dell'app (footer → Aggiornamenti) e i passaggi per riprodurre il problema. Non allegare contenuti di .ferret/ che mostrano schermate private.