Solución de problemas

#Falla la captura de pantalla o de ventana (macOS)

Mensaje: Grabar toda la pantalla u otra ventana requiere el permiso de Grabación de pantalla de macOS.

1. En el diálogo Objetivo de grabación, haz clic en Abrir Ajustes del Sistema.
2. Privacidad y seguridad → Grabación de pantalla y audio del sistema: activa Ferret.
3. Reinicia la app y haz clic en Volver a comprobar.

Grabar el Navegador integrado no necesita ningún permiso.

Al ejecutar desde el código fuente en macOS, pnpm dev inicia una copia de Electron renombrada y con firma ad hoc que también se llama Ferret (scripts/prepare-dev-electron.mjs), así que aparece como una entrada de Ferret aparte en estas listas. La primera vez que se ejecuta, macOS vuelve a pedir acceso a Grabación de pantalla y al Micrófono. Después ya no lo vuelve a pedir. Las versiones de desarrollo usan un llavero simulado (--use-mock-keychain), así que no aparece la solicitud del Llavero: las cookies y las claves guardadas en una versión de desarrollo se cifran con una clave fija, no con el Llavero real. Define ADE_DEV_REAL_KEYCHAIN=1 para usar el Llavero real.

#El micrófono no se abre

Mensaje: No se pudo abrir el micrófono. Revisa el permiso en los ajustes del sistema operativo.

• macOS: Ajustes del Sistema → Privacidad y seguridad → Micrófono y activa Ferret.
• Windows: Configuración → Privacidad y seguridad → Micrófono y permite el acceso a las aplicaciones de escritorio.

Sin micrófono, los círculos del lápiz siguen creando hallazgos, pero sin petición hablada.

#No hay modelo en el dispositivo / no se encuentra whisper-cli

Mensaje: No se encontró ningún modelo de transcripción en el dispositivo. Se guardará el audio y solo se procesarán los hallazgos de lápiz.

Descarga un modelo en Ajustes o elige un ggml-*.bin que ya tengas. Si Ajustes dice No se encontró whisper.cpp (whisper-cli), instálalo (instrucciones), asegúrate de que está en el PATH y vuelve a abrir Ajustes. Las apps empaquetadas abiertas desde el Finder o el Explorador pueden no ver el PATH de tu shell, así que instálalo en una ubicación estándar, como la de Homebrew.

Una descarga de modelo que no supera la comprobación sha256 se descarta. Vuelve a intentarlo.

#Terminal: no se pudo cargar node-pty

Ocurre al ejecutar desde el código fuente cuando node-pty se compiló para otra ABI de Node o de Electron.

pnpm rebuild:native

#No se encuentra el agente / Enviar al agente no envía

• command not found: claude (o codex, gemini u otro comando de agente) en la terminal: el CLI no está instalado o no está en el PATH. Ferret muestra el error propio de la shell y no añade ninguna pista. Comprueba que el comando funciona en tu terminal habitual, usa Instalar en Ajustes → Agentes o pon una ruta absoluta como Comando de ese agente.
• El agente está esperando confirmación. Responde en la terminal y luego envía. Responde primero a la pregunta del agente.
• La entrada del agente aún no está lista. Espera a que el agente termine de iniciarse.
• El texto se introdujo pero no se envió. Pulsa Intro en la terminal.
• Primero abre una terminal.
• No se pueden analizar los argumentos de inicio: Comilla sin cerrar. Corrige las comillas en los argumentos del agente.

#La grabación no empieza

• Primero abre una carpeta de proyecto.
• Primero abre una URL para revisar.
• La página no se cargó. Abre una URL que se muestre y luego graba. Comprueba que el servidor de desarrollo está en marcha. No se puede conectar con el servidor significa que no hay nada escuchando en ese puerto.

#Falta la clave de OpenAI o el endpoint

No hay ninguna clave de API de OpenAI configurada… o El endpoint de transcripción (Base URL / modelo) no está configurado…: añádelo en Ajustes o cambia a En el dispositivo (gratis). El audio de esa grabación ya está guardado.

#Errores de GitHub

• No se encontró GitHub CLI (gh). Instala gh.
• No has iniciado sesión en GitHub: Ajustes → GitHub / GitLab → Iniciar sesión en la terminal.
• No hay remoto origin. o origin no es un repositorio de GitHub. Comprueba git remote -v.
• No se encontró el repositorio o no tienes acceso. Comprueba gh auth status y GH_TOKEN.

#Informar de un error

Abre un issue en github.com/JapanMarketing-Dev/ferret/issues (se abre en una pestaña nueva) con tu sistema operativo, la versión de la app (pie de la ventana → Actualizaciones) y los pasos para reproducirlo. No adjuntes contenido de .ferret/ que incluya pantallas privadas.