Solução de problemas

#A captura da tela ou de janelas falha (macOS)

Mensagem: Gravar a tela inteira ou outra janela exige a permissão de Gravação de tela do macOS.

1. Na caixa de diálogo Alvo da gravação, clique em Abrir Ajustes do Sistema.
2. Privacidade e Segurança → Gravação de Tela e Áudio do Sistema: ative o Ferret.
3. Reinicie o app e clique em Verificar novamente.

Gravar o Navegador integrado não exige permissão.

Ao rodar a partir do código-fonte no macOS, o pnpm dev inicia uma cópia renomeada do Electron, com assinatura ad hoc, que também se chama Ferret (scripts/prepare-dev-electron.mjs); por isso ela aparece como uma entrada separada do Ferret nessas listas. Na primeira execução, o macOS pede de novo o acesso à Gravação de Tela e ao Microfone. Depois disso, não pede mais. As versões de desenvolvimento usam um keychain simulado (--use-mock-keychain), então não aparece o pedido do Keychain: cookies e chaves salvos em uma versão de desenvolvimento são criptografados com uma chave fixa, não com o Keychain real. Defina ADE_DEV_REAL_KEYCHAIN=1 para usar o Keychain real.

#O microfone não abre

Mensagem: Não foi possível abrir o microfone. Verifique a permissão nas configurações do sistema.

• macOS: Ajustes do Sistema → Privacidade e Segurança → Microfone e ative o Ferret.
• Windows: Configurações → Privacidade e segurança → Microfone e permita os aplicativos da área de trabalho.

Sem microfone, os círculos da caneta ainda criam apontamentos, mas sem pedido falado.

#Sem modelo no dispositivo / whisper-cli não encontrado

Mensagem: Nenhum modelo de transcrição no dispositivo encontrado. O áudio será salvo, e só os apontamentos de caneta serão processados.

Baixe um modelo nas Configurações ou escolha um ggml-*.bin existente. Se as Configurações disserem O whisper.cpp (whisper-cli) não foi encontrado, instale-o (instruções), confira se ele está no PATH e reabra as Configurações. Apps empacotados abertos pelo Finder ou pelo Explorer podem não enxergar o PATH do seu shell, então instale em um local padrão, como o do Homebrew.

Um download de modelo que falha na verificação do sha256 é descartado. Tente de novo.

#Terminal: não foi possível carregar o node-pty

Isso acontece ao rodar a partir do código-fonte quando o node-pty foi compilado para uma ABI diferente do Node ou do Electron.

pnpm rebuild:native

#Agente não encontrado / Enviar ao Agent não envia

• command not found: claude (ou codex, gemini ou o comando de outro agente) no terminal: a CLI não está instalada ou não está no PATH. O Ferret mostra o erro do próprio shell e não acrescenta dicas. Verifique se o comando funciona no seu terminal normal, use Instalar em Configurações → Agents ou defina um caminho absoluto como o Comando desse agente.
• O agent está aguardando confirmação. Responda no terminal e depois envie. Responda primeiro ao prompt do agente.
• A entrada do agent ainda não está pronta. Espere o agente terminar de iniciar.
• O texto foi digitado, mas não enviado. Aperte Enter no terminal.
• Abra um terminal primeiro.
• Não é possível interpretar os argumentos de inicialização: Aspas não fechadas. Corrija as aspas nos argumentos do agente.

#A gravação não começa

• Abra uma pasta de projeto primeiro.
• Abra uma URL para revisar primeiro.
• A página não carregou. Abra uma URL que seja exibida e depois grave. Verifique se o servidor de desenvolvimento está rodando. Não foi possível conectar ao servidor significa que nada está escutando naquela porta.

#Chave da OpenAI ou endpoint não definidos

Nenhuma chave de API da OpenAI definida… ou O endpoint de transcrição (Base URL / modelo) não está definido…: adicione-os nas Configurações ou troque para No dispositivo (gratuito). O áudio daquela gravação já está salvo.

#Erros do GitHub

• GitHub CLI (gh) não encontrado. Instale o gh.
• Sem login no GitHub. Configurações → GitHub / GitLab → Fazer login no terminal.
• Nenhum remote origin. ou origin não é um repositório do GitHub. Confira git remote -v.
• Repositório não encontrado ou você não tem acesso. Confira gh auth status e GH_TOKEN.

#Relatar um bug

Abra uma issue em github.com/JapanMarketing-Dev/ferret/issues (abre em uma nova aba) com o seu sistema operacional, a versão do app (rodapé → Atualizações) e os passos para reproduzir. Não anexe conteúdo de .ferret/ que contenha telas privadas.