Solución de problemas

Elige una sección por síntoma. Cada una tiene una lista de comprobación y correcciones ordenadas. Las figuras son PNG de vista previa de UI (public/screenshots/ts-*.webp).

Antes de empezar: anota estos cinco

1. Versión de macOS
2. Versión de VoiceHotkey (Ajustes → Acerca de)
3. Nombre del motor de reconocimiento
4. Solo local activado/desactivado
5. Ruta de la app (Finder → Obtener información)

Privacidad

Nunca pegues claves API, secretos de licencia ni transcripciones sensibles. Ver Contacto.

---

El atajo no hace nada

Sin overlay, sin cambio de estado en la barra de menú, sin retroalimentación del sistema.

Lista de comprobación

• Icono de la barra de menú presente (app en ejecución)
• Accesibilidad activada para la ruta actual de la app
• Iniciada desde /Applications o ~/Applications
• El atajo no entra en conflicto con otra app
• La página de atajos no advierte sobre Accesibilidad

Pasos

1. Proceso — El icono de la barra de menú debería abrir un menú. Reinicia desde Aplicaciones si falta.
2. Accesibilidad — Ajustes del Sistema → Privacidad y seguridad → Accesibilidad. Una fila de VoiceHotkey, ruta correcta, interruptor activado. Elimina duplicados, cierra y vuelve a abrir la app.
3. Ruta estable — Ver Instalación y permisos.
4. Reasignar — Ajustes → Atajos → graba una combinación menos común.
5. Conflictos — Cierra herramientas que choquen con los atajos por defecto: escritura ⌃⌥Space, comando ⌃⌥C.

Fig. A · Lista de Accesibilidad (vista previa · ts-01-accessibility-list.webp)

---

Graba pero no hay texto

El overlay muestra que escucha, pero el campo queda vacío o el procesamiento no termina.

Lista de comprobación

• Modo demo desactivado
• Micrófono concedido; dispositivo de entrada correcto
• Motor configurado (clave / Apple listo)
• Solo local no bloquea un motor en la nube
• Red / cuota / validez de la clave
• Cursor en un campo de texto normal (los campos seguros pueden bloquear la inserción)

Pasos

1. Ajustes → General — desactiva Modo demo.
2. Lee el estado de la barra de menú — micrófono necesario, motor no configurado, Solo local bloqueado, etc.
3. Micrófono — actívalo para VoiceHotkey; verifica el hardware con Notas de voz.
4. Motor — prueba Apple como control. Si Apple funciona pero la nube falla → clave/red/cuota.
5. Solo local — los motores públicos fallan cuando Solo local está activo.
6. Salida — la Acción de salida debería insertar en el cursor; prueba en Notas si Terminal bloquea la inyección.

Fig. B · Estado de la barra de menú (vista previa · ts-02-menubar-status.webp)

Fig. C · Solo local (vista previa · ts-03-local-only.webp)

---

Los permisos se resetean

Ayer funcionaba; hoy el atajo está muerto; Accesibilidad parece a medias.

Causas habituales

Causa	Notas
La ruta cambió	Descargas, otra carpeta o una ruta de build distinta
Firma / reemplazo	Una instalación sobrescrita se trata como una app nueva
Filas duplicadas	Entrada de Accesibilidad incorrecta vinculada

Solución

1. Mantén una sola app en Aplicaciones.
2. Cierra VoiceHotkey por completo.
3. Elimina todas las filas de VoiceHotkey en Accesibilidad y Micrófono.
4. Inicia desde la ruta fija y vuelve a conceder.
5. Abre siempre esa misma ruta (paquetes debug frente a release cuentan como rutas distintas).

---

El pulido / la traducción no cambian

• Pulido activado / usando el atajo de traducción
• Clave LLM de procesamiento de texto configurada
• Solo local no bloquea la API
• El respaldo puede insertar la transcripción en bruto (esperado en fallo)

1. Ajustes → Procesamiento de texto: pulido activado; la traducción usa su propio atajo.
2. Configura las claves del proveedor LLM.
3. Compara con Solo local desactivado, o apunta la Base URL a localhost.
4. Asegura que la escritura por voz simple funciona antes de activar el pulido.

---

Los comandos de voz no hacen nada

• Ajustes → Comandos de voz: ¿está activado «Activar comandos de voz» arriba?
• El atajo de comando no choca con escritura por voz/traducción y Accesibilidad está concedida
• «Permitir atajos de teclado» no está desactivado (si no, solo fallarán los atajos del diccionario)
• Entradas del diccionario de usuario activadas y frases que coincidan (primero exacta, luego difusa)

Ver Comandos de voz.

---

El comando shell no se ejecuta

• El interruptor general «Activar comandos de voz» está activado
• Trial o Pro (no Free)
• Ajustes → Comandos de voz → Permitir comandos shell activado
• No cancelaste el diálogo de confirmación
• No bloqueado por la lista de patrones peligrosos
• Si depende de la intención: modelo de intención activado y configurado; si depende del diccionario de usuario: entrada de tipo terminal y activada

Ver Comandos shell y Planes.

Fig. D · License (vista previa · ts-04-license.webp)

---

Escenarios rápidos

Instalación nueva

1. Ruta + ambos permisos
2. Modo demo desactivado
3. Un motor que funcione
4. Probar en Notas

Tras una actualización

1. Inicia la build nueva desde Aplicaciones
2. Limpia filas antiguas de Accesibilidad y vuelve a conceder
3. Confirma la versión en About

Red de trabajo / privacidad

1. Las API en la nube deben ser alcanzables
2. O usa Apple, los cuatro motores en dispositivo o localhost
3. Solo local también pausa las comprobaciones de actualización

---

Si sigues atascado

1. Vuelve a hacer la prueba en seco de la configuración inicial.
2. Reúne los cinco puntos del inicio.
3. Abre un issue en Contacto.

Instalación y permisosDMG, ruta, Accesibilidad, micrófono.

Configuración inicialModo demo, motor, atajos, prueba.