# 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