He visto a OpenClaw hacer cosas extrañas. Se cierra sin mensajes de error. Responde en el idioma incorrecto sin razón aparente. Se niega a reconocer que existe un canal de Slack perfectamente configurado. Una vez, comenzó a responder a cada mensaje con un haiku. No pedí el modo haiku. No hay modo haiku.
Después de ocho meses y aproximadamente 400 momentos de “¿qué demonios?”, he recopilado los 10 problemas que he visto con más frecuencia — tanto por mi propia experiencia como por ayudar a personas en el Discord de la comunidad. No son problemas teóricos de casos extremos documentados. Estas son las cosas que realmente fallan en instalaciones reales.
1. Síndrome de “Estaba Funcionando Ayer”
El problema más común de OpenClaw no es un error — es una clave API que ha caducado, un modelo que ha sido descontinuado o un endpoint de servicio que ha cambiado. No cambiaste nada, pero algo en el sistema lo hizo.
Diagnosis: Revisa primero la página de estado de tu proveedor de modelos. Luego verifica la validez de tu clave API. Después, comprueba si el nombre del modelo en tu configuración aún existe. Nueve de cada diez veces, el problema es externo.
Solución: Actualiza la clave, el nombre del modelo o el endpoint. Y establece un recordatorio en el calendario para revisar esto mensualmente, porque los proveedores cambian cosas sin avisarte.
2. La Fuga de Memoria que Consume Tu Servidor
Después de correr durante unos días, OpenClaw se vuelve lento, luego más lento, y finalmente se cierra. El uso de memoria aumenta constantemente hasta que el sistema operativo mata el proceso.
Diagnóstico: Casi siempre es un contexto de conversación que crece sin límites. Cada mensaje se añade al contexto, y si los mensajes antiguos no se están podando, eventualmente el contexto consume toda la memoria disponible.
Solución: Configura la compactación de contexto. Establece un tamaño máximo para el contexto. Activa la poda automática de mensajes antiguos. Reinicia el servicio después de aplicar la solución y observa el uso de memoria durante 24 horas para confirmar que se estabiliza.
3. Bot de Slack/Discord No Responde
Has configurado todo, el bot muestra “en línea” en Slack/Discord, pero no responde a ningún mensaje.
Diagnóstico: Generalmente es un problema de permisos. El bot necesita permisos específicos (leer mensajes, escribir mensajes, leer canales) y debe ser invitado explícitamente a cada canal. Otra causa común: la URL del webhook no es accesible desde el exterior.
Solución: Revisa los permisos del bot en la consola de desarrolladores de la plataforma. Verifica que el bot sea miembro del canal en el que estás probando. Prueba la URL del webhook desde una fuente externa (usa un servicio como httpbin o requestbin para verificar que tu endpoint sea accesible).
4. Trabajos Cron Ejecutándose Pero Produciendo Salida Vacía
Tu trabajo programado se ejecuta a tiempo (puedes verlo en los registros) pero la salida está vacía o no tiene sentido.
Diagnóstico: El prompt probablemente sea demasiado vago o referencia datos a los que el agente no puede acceder. “Resume las métricas de hoy” fallará si el agente no tiene acceso a la base de datos de métricas. El trabajo se ejecuta, la IA no tiene nada con qué trabajar y produce basura.
Solución: Prueba el prompt exacto como tarea manual primero. Asegúrate de que todas las fuentes de datos sean accesibles. Incluye instrucciones explícitas sobre dónde encontrar los datos.
5. Las Respuestas Son Dolorosamente Lentas
Cada respuesta tarda de 15 a 30 segundos en lugar de los 2-3 segundos esperados.
Diagnóstico: Tres causas comunes. Primero: tu contexto de conversación es demasiado grande (el modelo tiene que procesar miles de tokens de historia antes de generar una respuesta). Segundo: la API del modelo es lenta (revisa el estado del proveedor). Tercero: latencia de red entre tu servidor y el endpoint de la API.
Solución: Para el tamaño del contexto: activa la compactación, limita la longitud de la historia. Para la lentitud de la API: espera, cambia de proveedor temporalmente o usa una respuesta en caché cuando sea posible. Para la red: considera alojar más cerca de la región del proveedor de la API.
6. Errores de “Rate Limited”
Explosiones repentinas de errores 429, o el bot quedándose en silencio durante el uso máximo.
Diagnóstico: Estás superando el límite de tasa de tu proveedor de API. Esto ocurre cuando múltiples usuarios interactúan simultáneamente o cuando un flujo de trabajo activa muchas llamadas a la API en rápida sucesión.
Solución: Implementa una cola de solicitudes con programación consciente del límite de tasa. Actualiza tu nivel de API si el nivel gratuito es demasiado restrictivo. Para escenarios de ráfaga, agrega retroceso exponencial (espera y vuelve a intentar con retrasos crecientes).
7. El Agente Dice Cosas Que No Debe
El agente revela detalles del prompt del sistema, responde de manera inapropiada o se desvía del tema de maneras que parecen inyecciones de prompt.
Diagnóstico: Si el agente está expuesto a entradas no confiables (canales públicos, mensajes de usuario), es probable que haya inyección de prompt. Alguien elaboró una entrada que anula tus instrucciones del sistema.
Solución: Agrega filtrado de salida para patrones sensibles (claves API, fragmentos de prompts del sistema). Implementa validación de entrada para patrones de inyección conocidos. Para configuraciones de alta seguridad, procesa la entrada no confiable en un contexto separado de las instrucciones del sistema.
8. Fallos en la Conexión a la Base de Datos
El agente no puede conectarse a tu base de datos, o las conexiones se interrumpen de forma intermitente.
Diagnóstico: Agotamiento del grupo de conexiones (demasiadas conexiones abiertas), problemas de autenticación (contraseña cambiada, certificado SSL caducado), o problemas de red (cortafuegos bloqueando, fallo en la resolución DNS).
Solución: Verifica la configuración del grupo de conexiones y aumenta si es necesario. Confirma las credenciales. Prueba la conexión de forma independiente (usa un cliente de base de datos para confirmar que puedes conectarte con las mismas credenciales desde el mismo servidor).
9. Permisos del Sistema de Archivos
El agente no puede leer ni escribir archivos, a pesar de que las rutas parecen correctas.
Diagnóstico: El proceso de OpenClaw se ejecuta bajo una cuenta de usuario específica. Esa cuenta de usuario necesita permisos de lectura/escritura en los directorios que el agente intenta acceder.
Solución: Verifica qué usuario ejecuta OpenClaw. Asegúrate de que ese usuario tenga los permisos apropiados en los directorios de destino. En Linux: ls -la para comprobar, chown o chmod para solucionar. No uses permisos 777 — otorga el acceso mínimo necesario.
10. Las Actualizaciones Rompen Todo
Actualizas OpenClaw y tu configuración cuidadosamente configurada deja de funcionar.
Diagnóstico: Cambios en el formato de configuración entre versiones, características descontinuadas eliminadas o conflictos de dependencias. Este es el problema más frustrante porque no cambiaste tu código — solo querías las últimas funciones.
Solución: Lee el registro de cambios antes de actualizar. Realiza una copia de seguridad de tu configuración antes de actualizar. Prueba la actualización primero en una instancia de desarrollo. Si algo se rompe, tu copia de seguridad te permite retroceder de inmediato. Nunca actualices producción sin una copia de seguridad verificada y un plan de retroceso.
El Enfoque Universal de Depuración
Cuando algo falla y no sabes por qué:
1. Revisa los registros (el 90% de las respuestas están en los registros)
2. Revisa servicios externos (estado de la API, conexión a la base de datos, red)
3. Revisa qué cambió (¿actualizaste algo? ¿Cambió algo el proveedor?)
4. Reproduce el problema (¿puedes desencadenarlo de manera consistente?)
5. Busca en el Discord de la comunidad (probablemente alguien más ya enfrentó esto)
Y cuando todo lo demás falla: reinicia el servicio y ve si el problema desaparece. No debería ser el primer paso, pero es un último recurso válido. A veces, las computadoras simplemente son computadoras.
🕒 Published: