Solución de problemas

Empieza por el icono de estado

Antes de nada, abre el corazón de la barra superior: es el estado de la aplicación. Te dice en una frase si hay una IA conectada, si el modelo elegido sigue existiendo, si hay internet y si falta algún programa auxiliar — y cada aviso trae un botón Arreglar que te lleva al paso concreto que falta.

Los errores del chat también salen ya en lenguaje llano, con su acción: «Esta IA todavía no tiene tu cuenta» → Conectar mi IA; «Ese modelo ya no está disponible» → Elegir otro modelo; «Has llegado al límite de tu plan» → Usar otra IA; «No hay conexión a internet» → Instalar una IA local; «Falta un programa que esto necesita» → Ver qué falta.

El chat no responde

La causa número uno: el perfil activo del proveedor no tiene credenciales válidas.

1. Abre el selector de proveedor (junto al campo del chat) y mira el estado: debe decir Conectado. Si dice Sin autenticar, conéctalo de nuevo.
2. Ojo al detalle: la conexión es por perfil. Puedes tener el proveedor conectado en un perfil y estar usando otro sin credenciales — revisa cuál está activo en el chat.
3. Con proveedores OAuth (Claude, OpenAI, Copilot): los tokens caducados se renuevan solos, pero si revocaste el acceso desde tu cuenta, la renovación falla — inicia sesión otra vez.
4. Si acabas de cambiar de proveedor o modelo a mitad de chat y algo quedó raro, envía el mensaje de nuevo tras verificar el estado del proveedor.

El agente no hace nada, solo habla

Revisa el modo de aprobación: en Solo lectura el agente no puede escribir archivos ni ejecutar comandos, por diseño. Sube a «Solicitar aprobación» o superior.

No hay autocompletado ni errores en el editor

El servidor de lenguaje (LSP) de ese lenguaje no está instalado. La app te lo avisa al abrir el archivo y te ofrece instalarlo desde el propio aviso; también puedes administrarlos en la pestaña LSP del panel de extensiones — ver Skills, MCP y plugins.

Problemas con modelos locales

• Ollama / LM Studio no aparecen o no listan modelos: comprueba que la aplicación externa esté corriendo y que tenga modelos instalados; luego reintenta desde el selector de proveedor.
• Context Forge no responde en la pestaña API: el servidor arranca al ejecutar un modelo. Ve a Catálogo → Instalados y pulsa Ejecutar en uno; comprueba que el campo model de tus peticiones sea el id de un modelo en ejecución.
• La API key de Forge dejó de funcionar: cambia en cada arranque del servidor; copia la nueva desde la pestaña API.
• El modelo va lento o el equipo se queda sin memoria: prueba una cuantización más pequeña del mismo modelo, o usa Liberar memoria / Detener motor local en la barra superior para descargar modelos que no estés usando.

Gemini responde «el modelo está saturado»

Con Gemini API Key la app ya reintenta sola tres veces ante un 503 o un 429 (a los 2, 5 y 10 segundos). Si aun así el mensaje insiste —«Google reporta saturación del modelo»—, el problema está en el lado de Google: espera un momento y vuelve a enviar, o cambia a otro modelo del catálogo desde el selector del chat.

La conversación de voz no arranca

• «el servidor LiveKit no arrancó»: pulsa Reintentar. Desde la 3.6.0 el motor viene dentro del instalador y no hay nada que descargar; si se repite, mira que nada esté ocupando el puerto 7880 y que tu antivirus no esté bloqueando el servidor.
• «el agente de voz se cerró antes de registrarse»: cierra la conversación, espera unos segundos y pulsa Reintentar. Si persiste, reinicia la aplicación.
• El micrófono no entra: los micrófonos «virtuales» publican silencio — elige otro en el selector de Micrófono. En Windows, revisa Configuración → Privacidad y seguridad → Micrófono y activa «Permitir que las aplicaciones de escritorio accedan al micrófono».
• Se activa con el ruido del teclado: el detector está calibrado para ignorar clics, pero un micrófono pegado a un teclado mecánico sigue siendo mala idea. Usa unos auriculares con micro.
• Elegí una voz de Groq y suena otra: algunas voces de Groq exigen aceptar sus términos en tu cuenta. Mientras tanto la app no cuelga la llamada: responde con Edge TTS.
• Todo el detalle, en Conversación en tiempo real.

La consola SQL perdió la conexión

Desde la 3.6 no debería: la conexión sobrevive al cambio de sección y hay reconexión automática. Si aun así falla:

• Tras reconectar, la sesión es nueva: no conserva el USE ni las tablas temporales del script anterior. Vuelve a ejecutarlos.
• Un error de SQL (columna inexistente, restricción violada) no se reintenta a propósito — repetir un INSERT a ciegas sería peor. Corrige la consulta.
• Si el script nombra otra base, la consola avisa: usa Reescribir a… o Quitar prefijos de base.

El teléfono no conecta (app móvil / acceso web)

• En red local, teléfono y PC deben estar en la misma WiFi. El modo Conversación desde el móvil solo funciona por WiFi local, nunca por el túnel público.
• El token del QR caduca (configurable de 1 minuto a 24 horas): genera un QR nuevo y vuelve a escanear.
• Si rotaste el token, todos los enlaces anteriores quedan invalidados — es lo esperado.
• Para acceso desde fuera de casa, crea la URL pública (túnel) desde el panel de Acceso web; la red local no basta.

Un canal de mensajería no responde

• ¿Configuraste la lista de usuarios autorizados? Sin ella, el bot no responde a nadie — es una medida de seguridad, no un fallo.
• WhatsApp: si cerraste sesión desde el teléfono (Dispositivos vinculados), hay que volver a escanear el QR.
• Telegram: verifica el Bot Token de @BotFather y escríbele /start al bot desde tu cuenta.
• Slack: la app necesita los scopes chat:write y channels:history, y el ID del canal correcto.

El workspace por SSH se cae cada poco

Casi siempre es el NAT de tu router o la VPN, que reciclan las sesiones ociosas porque no ven el tráfico cifrado que SSH manda por dentro. Desde la 3.6 la conexión lleva keep-alive en las dos capas y, si aun así se corta, la aplicación detecta el túnel muerto y vuelve sola a trabajar en local en vez de encadenar esperas por cada comando. Cuando la red vuelve, reintenta con esperas crecientes durante más de dos minutos.

Si te pasa constantemente, mira si tu VPN tiene un tiempo de inactividad agresivo.

contextcode no existe como comando

Depende de cómo instalaste: el .deb y el instalador .exe de Windows dejan el comando en el PATH, pero el AppImage, el .dmg de macOS y el .msi no pueden. El arreglo es una línea:

contextcode instalar-cli

Detalle completo en Context Code desde la terminal. En Windows, acuérdate de abrir una terminal nueva después.

No sé qué instalación estoy usando

contextcode conexion

Te dice la versión, el ejecutable, las carpetas de configuración y datos, la base de datos y el estado del enlace remoto — y marca con (DESARROLLO) los builds de desarrollo, que usan carpetas aparte. Es la causa habitual de «edité la configuración y no pasa nada»: la editaste en la otra instalación. Ver su página.

Las automatizaciones no corrieron

Si la app estaba cerrada y el daemon (ejecución en segundo plano) estaba inactivo, las automatizaciones no corren — actívalo en el panel de Automatizaciones. La pestaña Historial muestra cada ejecución con su detalle.

Sigue sin funcionar

Vuelve a pasar la guía de bienvenida (menú de tu cuenta → «Volver a ver la guía», o Configuración → General): recorre idioma, IA, proyecto y voz, y deja la aplicación lista sin que tengas que buscar nada.

Si aun así falla, reinicia la aplicación (ciérrala también de la bandeja del sistema) y vuelve a intentarlo. Si el problema persiste, anota el texto exacto del error — con él, el soporte (o tu propio agente) llega mucho más lejos.