Solución de problemas

¿Algo no funciona? ¡Tranquilo! Sigue estos pasos de diagnóstico y la mayoría de los problemas se pueden resolver por tu cuenta.

🔍 Escalera de diagnóstico (sigue el orden)

Cuando OpenClaw tenga algún problema, sigue estos pasos en orden:

Comprueba el estado

openclaw status

Verifica si OpenClaw sigue en funcionamiento. Si muestra "stopped" o da un error, intenta reiniciarlo primero.

Comprueba el estado del gateway

openclaw gateway status

El gateway es el puente que conecta OpenClaw con las plataformas de chat. Si el estado del gateway es anormal, los mensajes no se podrán enviar ni recibir.

Revisa los registros (logs)

openclaw logs

Los registros contienen todos los detalles de funcionamiento de OpenClaw. Si hay un error, normalmente encontrarás un mensaje de error en rojo que te indica qué salió mal.

Ejecuta el chequeo de salud

openclaw doctor

Un chequeo completo que te dirá qué componentes funcionan correctamente y cuáles tienen problemas.

Comprueba la conexión de los canales

openclaw channels status

Verifica el estado de conexión de cada canal de chat para ver si alguno se ha desconectado.

🐛 Errores comunes y soluciones

Error: "openclaw: command not found"

Causa: El sistema no encuentra el comando openclaw, normalmente es un problema con la variable de entorno PATH.

Solución:

# Comprobar dónde está instalado openclaw
npm list -g openclaw

# Añadir el directorio global de npm al PATH
export PATH="$(npm config get prefix)/bin:$PATH"

# Añadir el comando anterior a tu archivo de configuración de shell para que sea permanente
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Error: Conflicto de puertos (EADDRINUSE: address already in use :::18789)

Causa: El puerto 18789 ya está ocupado por otro programa.

Solución:

# Buscar el proceso que ocupa el puerto
lsof -i :18789

# Detener el proceso antiguo de OpenClaw
openclaw stop

# Si no es un proceso de OpenClaw, puedes cambiar el puerto en la configuración
# Edita ~/.openclaw/openclaw.json y modifica el valor de port

Error: 429 Too Many Requests (límite de velocidad)

Causa: Estás enviando peticiones con demasiada frecuencia. Los proveedores de modelos de IA tienen límites de frecuencia en las llamadas API.

Solución:

Espera unos minutos e inténtalo de nuevo
Reduce la frecuencia de envío de mensajes
Actualiza tu plan de pago de la API para obtener límites de velocidad más altos
Considera cambiar a un proveedor de modelos con límites más flexibles

Error: El gateway no puede iniciarse

Causa: Puede ser un token de Bot inválido, un problema de conexión de red, o un cambio en la API de la plataforma de chat.

Solución:

# Revisar los registros del gateway
openclaw gateway logs

# Verificar si el token del Bot es válido
openclaw channels verify

# Reiniciar el gateway
openclaw gateway restart

Error: Los mensajes no se envían

Causa: Puede ser una configuración de canal incorrecta, un problema de red, o permisos insuficientes del Bot.

Solución:

Comprueba el estado de los canales: openclaw channels status
Confirma que el Bot tiene permisos de envío de mensajes en la plataforma correspondiente
Verifica que la conexión de red funcione correctamente
Revisa los registros en busca de mensajes de error específicos

Error: El panel de control no se abre

Causa: Es posible que el servicio de OpenClaw no esté en funcionamiento, o la configuración del puerto sea incorrecta.

Solución:

# Confirmar que OpenClaw está en funcionamiento
openclaw status

# Si no está en funcionamiento, inícialo
openclaw start

# Luego intenta abrir el panel de control
openclaw dashboard

# O accede directamente desde el navegador
# http://127.0.0.1:18789/

🆘 ¿Sigue sin resolverse?

Si después de seguir los métodos anteriores el problema persiste, puedes:

Buscar o reportar el problema en GitHub Issues
Unirte a la comunidad de Discord de OpenClaw para pedir ayuda
Al preguntar, incluye la salida de openclaw doctor y openclaw logs