Solucion de Problemas

Problemas comunes y como resolverlos.

Problemas del Gateway

El Gateway no inicia

• Conflicto de puerto -- Otro proceso puede estar usando el puerto 18789. Verifique con lsof -i :18789.
• Error de configuracion -- JSON invalido en neotask.json. El Gateway valida la configuracion al iniciar y reporta errores especificos.
• Bloqueo del Gateway -- Una instancia anterior puede haber dejado un archivo de bloqueo obsoleto. La herramienta de diagnostico puede detectar y corregir esto.
• Version de Node.js -- Neotask requiere Node 22+.

El Gateway inicia pero no se conectan canales

• Credenciales faltantes -- Cada canal necesita su propia autenticacion (token de bot, escaneo QR, clave API).
• Problemas de red -- Los canales necesitan acceso a internet para conectarse a las APIs de plataformas de mensajeria.
• Limites de tasa -- Algunas plataformas limitan la tasa de nuevas conexiones. Espere y reintente.

No se puede conectar desde la aplicacion de escritorio

• Puerto incorrecto -- Asegurese de que la aplicacion de escritorio se conecta al puerto correcto del Gateway.
• Autenticacion no coincide -- El token del Gateway debe coincidir.
• Firewall -- Asegurese de que el puerto sea accesible si el Gateway esta en otra maquina.

Problemas de Canales

WhatsApp no se conecta

• QR expirado -- Los codigos QR expiran despues de ~60 segundos. Re-escanee rapidamente.
• Limite de multi-dispositivo -- WhatsApp limita los dispositivos vinculados.
• Sesion corrupta -- Elimine el directorio de sesion de WhatsApp y vuelva a emparejar.

El bot de Telegram no recibe mensajes

• Token de bot invalido -- Verifique su token de bot con BotFather.
• Modo de privacidad -- Los bots solo ven mensajes cuando se los menciona en grupos por defecto.
• Conflicto de webhook -- Otro servicio puede estar consumiendo los mensajes.

El bot de Discord no responde

• Intents faltantes -- Habilite los Gateway Intents requeridos en el Portal de Desarrolladores de Discord.
• Permisos faltantes -- El bot necesita permisos de lectura y envio en los canales objetivo.

Problemas de Modelos

Errores de autenticacion

• Clave no configurada -- Asegurese de que la clave API del proveedor este establecida.
• Clave expirada -- Algunos tokens OAuth expiran. Re-autentiquese.
• Limite de tasa -- La rotacion de claves cambiara automaticamente si tiene multiples claves.

Respuestas lentas

• Eleccion de modelo -- Los modelos mas grandes son mas lentos. Pruebe un modelo mas rapido para tareas rapidas.
• Tamano de contexto -- Las conversaciones largas ralentizan el procesamiento. Pruebe /compact.
• Latencia de red -- Verifique la conectividad con su proveedor de modelos.

Problemas de Nodos

La aplicacion companion no encuentra el Gateway

• Modo de vinculacion -- El Gateway debe estar vinculado a LAN o Tailnet (no loopback) para dispositivos externos.
• Misma red -- Para descubrimiento Bonjour, ambos dispositivos deben estar en la misma red.
• Entrada manual -- Ingrese el host y puerto del Gateway manualmente en los ajustes de la app.

Problemas de Sesion

Ventana de contexto excedida

• Compactar -- Use /compact para resumir y reiniciar el contexto.
• Habilitar auto-compactacion -- Establezca un umbral de compactacion en la configuracion.
• Nueva sesion -- Comience de nuevo con /new.

Diagnosticos

La herramienta de diagnostico integrada verifica problemas comunes y puede corregir muchos automaticamente:

• Validacion de configuracion
• Permisos de archivos
• Conectividad de canales
• Estado de autenticacion de modelos
• Compatibilidad de Node.js
• Configuracion de red

Verifique los logs del Gateway para informacion detallada de errores. El endpoint /health proporciona estado legible por maquina de todos los componentes.

Obteniendo Ayuda

1. Ejecute la herramienta de diagnostico para correcciones automatizadas
2. Verifique los logs del Gateway para mensajes de error detallados
3. Contacte soporte a traves del widget de chat Intercom en la aplicacion de escritorio