Blog

Cómo Solucionar Errores de OpenClaw: 15 Problemas Comunes y Soluciones

Ashley Innocent

Ashley Innocent

5 March 2026

Cómo Solucionar Errores de OpenClaw: 15 Problemas Comunes y Soluciones

TL;DR

La resolución de problemas de OpenClaw cubre caídas de conexión, fallos de autenticación, errores de enrutamiento y problemas de rendimiento. La mayoría de los problemas provienen de inestabilidad de la red, claves API incorrectas o canales mal configurados. Esta guía proporciona soluciones paso a paso para los 15 errores más comunes de OpenClaw.

Problemas de instalación y configuración

Desajuste de versión de Node.js

Problema: Comando openclaw no encontrado o falla con "versión de Node no compatible".

Causa: OpenClaw requiere Node.js 22 o posterior. Las versiones anteriores carecen de las características necesarias.

Solución:

Verifica tu versión de Node:

node --version

Si es inferior a 22, actualiza Node:

# Usando nvm (recomendado)
nvm install 22
nvm use 22

# O descarga desde nodejs.org

Reinstala OpenClaw:

npm install -g openclaw@latest

Verifica la instalación:

openclaw --version

Permiso denegado durante la instalación

Problema: npm install -g openclaw falla con errores EACCES o de permisos.

Causa: npm intenta escribir en directorios del sistema sin los permisos adecuados.

Solución:

No uses sudo. En su lugar, configura npm para usar un directorio de usuario:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

Añádelo a tu perfil de shell (~/.zshrc o ~/.bashrc):

export PATH=~/.npm-global/bin:$PATH

Recarga tu shell:

source ~/.zshrc

Instala OpenClaw:

npm install -g openclaw@latest

Archivo de configuración no encontrado

Problema: OpenClaw no encuentra ~/.openclaw/config.json después de la instalación.

Causa: El asistente de configuración inicial no se ejecutó o falló silenciosamente.

Solución:

Ejecuta la configuración inicial manualmente:

openclaw onboard

Si eso falla, crea el directorio de configuración:

mkdir -p ~/.openclaw

Crea un archivo de configuración mínimo:

cat > ~/.openclaw/config.json << 'EOF'
{
  "version": "1.0.0",
  "providers": {},
  "agents": {},
  "channels": {},
  "routing": []
}
EOF

Ejecuta la configuración inicial de nuevo:

openclaw onboard

Problemas de conexión de canal

El código QR de WhatsApp no escanea

Problema: El código QR aparece pero la aplicación de WhatsApp dice "Código QR no válido" o no responde.

Causa: El código QR ha caducado o hay problemas de red entre tu teléfono y OpenClaw.

Solución:

  1. Asegúrate de que tu teléfono y computadora estén en la misma red.
  2. Vuelve a generar el código QR:
openclaw channels logout whatsapp
openclaw channels login whatsapp
  1. Escanea en los 30 segundos siguientes (los códigos QR caducan rápidamente).
  2. Si sigue fallando, verifica la configuración del firewall:
# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/node

# Linux (ufw)
sudo ufw allow 18789/tcp

WhatsApp se desconecta después de unas horas

Problema: WhatsApp funciona inicialmente pero se desconecta después de 2-4 horas.

Causa: El protocolo de WhatsApp requiere latidos periódicos. Cambios en la red o el modo de suspensión interrumpen la conexión.

Solución:

Habilita la reconexión automática:

openclaw channels config whatsapp --auto-reconnect true --reconnect-interval 300

Esto verifica la conexión cada 5 minutos y se reconecta si es necesario.

Si estás en una laptop, evita que entre en suspensión mientras OpenClaw se ejecuta:

# macOS
caffeinate -i openclaw gateway

# Linux
systemd-inhibit --what=sleep openclaw gateway

Para producción, ejecuta OpenClaw en un servidor en lugar de una laptop.

El bot de Telegram no recibe mensajes

Problema: El bot está en línea pero no responde a los mensajes.

Causa: El bot carece de los permisos necesarios o el token es inválido.

Solución:

Prueba el token del bot:

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

Si esto devuelve un error, regenera el token:

  1. Abre Telegram y envía un mensaje a @BotFather.
  2. Envía /mybots.
  3. Selecciona tu bot.
  4. Elige "API Token" → "Regenerate Token".
  5. Actualiza OpenClaw:
openclaw channels update telegram --token NEW_TOKEN

Para chats grupales, agrega el bot como administrador con permiso de "Leer Mensajes".

El bot de Discord aparece desconectado

Problema: El bot aparece desconectado en la lista de servidores de Discord.

Causa: Falta "Message Content Intent" o token inválido.

Solución:

  1. Ve al Portal de Desarrolladores de Discord.
  2. Selecciona tu aplicación.
  3. Ve a la pestaña "Bot".
  4. Habilita "Message Content Intent" bajo Privileged Gateway Intents.
  5. Guarda los cambios.
  6. Reinicia OpenClaw:
openclaw gateway restart

Si el bot sigue desconectado, verifica el token:

openclaw channels test discord

Si falla, regenera el token en el Portal de Desarrolladores y actualiza OpenClaw.

El puente de iMessage no funciona (macOS)

Problema: El canal de iMessage muestra "desconectado" o no recibe mensajes.

Causa: Faltan permisos de accesibilidad o la aplicación Mensajes no se está ejecutando.

Solución:

  1. Abre Configuración del Sistema → Privacidad y Seguridad → Accesibilidad.
  2. Agrega Terminal (o tu aplicación de terminal) a la lista permitida.
  3. Reinicia OpenClaw:
openclaw gateway restart
  1. Asegúrate de que la aplicación Mensajes esté ejecutándose y con sesión iniciada.
  2. Prueba enviándote un mensaje a ti mismo.

Si aún no funciona, verifica el proceso del puente:

ps aux | grep openclaw-imessage-bridge

Si no se está ejecutando, inícialo manualmente:

openclaw channels restart imessage

Errores de autenticación y API

Clave API inválida

Problema: Errores de "Autenticación fallida" o "Clave API inválida" en los registros.

Causa: Clave API incorrecta, clave caducada o clave sin los permisos adecuados.

Solución:

Verifica tu clave API:

# Para Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

# Para OpenAI
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hi"}],"max_tokens":10}'

Si el comando curl falla, tu clave es inválida. Obtén una nueva desde el panel de control de tu proveedor.

Actualiza OpenClaw:

openclaw config set --provider anthropic --api-key NEW_KEY

Reinicia el Gateway:

openclaw gateway restart

Límite de tasa excedido

Problema: Errores de "Límite de tasa excedido" o "Demasiadas solicitudes".

Causa: Estás enviando demasiadas solicitudes a tu proveedor de IA.

Solución:

Verifica tu uso:

openclaw stats --period 1h

Habilita la limitación de tasa:

openclaw limits set --max-requests 50 --window 3600

Esto te limita a 50 solicitudes por hora. Ajústalo según los límites de tu proveedor.

Para tráfico en ráfaga, habilita la cola:

openclaw config set --enable-queue true --queue-max-size 100

Los mensajes se ponen en cola cuando alcanzas el límite de tasa y se procesan cuando hay capacidad disponible.

Modelo no encontrado

Problema: Errores de "Modelo no encontrado" o "Modelo inválido".

Causa: Has especificado un modelo que no existe o no está disponible para tu cuenta.

Solución:

Lista los modelos disponibles:

# Anthropic
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: YOUR_KEY"

# OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

Actualiza la configuración de tu agente:

openclaw agents update default --model claude-sonnet-4-6

Reinicia el Gateway:

openclaw gateway restart

Créditos insuficientes

Problema: Errores de "Créditos insuficientes" o "Pago requerido".

Causa: Tu cuenta de proveedor de IA se quedó sin créditos o alcanzó los límites de facturación.

Solución:

Verifica el saldo de tu cuenta en el panel de control de tu proveedor:

Agrega créditos o actualiza tu método de pago.

Mientras esperas, enruta a un modelo gratuito o local:

openclaw agents add fallback --provider ollama --model llama2
openclaw routing add --fallback fallback

Fallos de enrutamiento de mensajes

Los mensajes van al agente equivocado

Problema: Los mensajes se enrutan al agente de IA incorrecto a pesar de las reglas de enrutamiento.

Causa: Las reglas de enrutamiento entran en conflicto o tienen prioridades incorrectas.

Solución:

Lista todas las reglas de enrutamiento:

openclaw routing list

Verifica conflictos. Las reglas con mayor prioridad coinciden primero. Si tienes:

Prioridad 5: canal=whatsapp → agente=default
Prioridad 10: remitente=+1234567890 → agente=vip

Los mensajes de +1234567890 en WhatsApp irán a vip (la prioridad 10 gana).

Elimina las reglas en conflicto:

openclaw routing remove <rule-id>

Agrega reglas con las prioridades correctas:

openclaw routing add --channel whatsapp --agent default --priority 1
openclaw routing add --sender +1234567890 --agent vip --priority 10

Prueba el enrutamiento:

openclaw routing test --channel whatsapp --sender +1234567890 --message "test"

Esto muestra qué agente manejaría el mensaje sin enviarlo.

El enrutamiento por palabra clave no funciona

Problema: Los mensajes con palabras clave específicas no se enrutan al agente configurado.

Causa: Las palabras clave distinguen entre mayúsculas y minúsculas o el mensaje no contiene la palabra clave exacta.

Solución:

Haz que las palabras clave no distingan entre mayúsculas y minúsculas:

openclaw routing add --keyword "debug" --agent debugging --case-insensitive

Usa expresiones regulares para una coincidencia flexible:

openclaw routing add --pattern "debug|error|bug" --agent debugging

Esto coincide con "debug", "error" o "bug" en cualquier parte del mensaje.

Prueba la coincidencia de palabras clave:

openclaw routing test --message "I found a debug issue"

Errores de la función de enrutamiento personalizada

Problema: La función de enrutamiento personalizada arroja errores o no se ejecuta.

Causa: Errores de sintaxis, dependencias faltantes o valores de retorno incorrectos.

Solución:

Prueba tu función de enrutamiento:

openclaw routing test-custom ~/.openclaw/routing.js --message "test"

Esto ejecuta tu función y muestra el resultado o error.

Problemas comunes:

  1. Errores de sintaxis: Revisa tu sintaxis de JavaScript.
  2. Falta de retorno: Siempre devuelve un nombre de agente.
  3. Funciones asíncronas: No uses async/await en funciones de enrutamiento (deben ser síncronas).

Ejemplo de función correcta:

module.exports = function route(message) {
  // Siempre devuelve una cadena (nombre del agente)
  if (message.channel === 'whatsapp') {
    return 'whatsapp-agent';
  }
  return 'default';
};

Ejemplo de función incorrecta:

// NO HAGAS ESTO
module.exports = async function route(message) {
  const result = await someAsyncOperation();
  return result; // Las funciones asíncronas no son compatibles
};

El agente de respaldo no se activa

Problema: Cuando el agente principal falla, los mensajes no se enrutan al de respaldo.

Causa: El respaldo no está configurado o el agente principal no informa los fallos correctamente.

Solución:

Configura el respaldo:

openclaw routing set-fallback backup-agent

Prueba el respaldo:

# Deshabilita temporalmente el agente principal
openclaw agents disable default

# Envía un mensaje de prueba
openclaw routing test --message "test"

# Debería mostrar el agente de respaldo

Vuelve a habilitar el agente principal:

openclaw agents enable default

Problemas de rendimiento y memoria

Uso elevado de memoria

Problema: OpenClaw usa más de 2GB de RAM y sigue creciendo.

Causa: Los datos de la sesión se acumulan con el tiempo sin limpieza.

Solución:

Verifica el uso de memoria:

openclaw stats --memory

Borra sesiones antiguas:

openclaw sessions clear --older-than 7d

Reduce el tiempo de espera de la sesión:

openclaw config set --session-timeout 1800

Las sesiones ahora caducan después de 30 minutos de inactividad en lugar de la hora predeterminada.

Habilita la limpieza automática:

openclaw config set --auto-cleanup true --cleanup-interval 3600

Esto ejecuta la limpieza cada hora.

Tiempos de respuesta lentos

Problema: Las respuestas de IA tardan más de 30 segundos o expiran.

Causa: Latencia de red, proveedor de IA lento o cola de espera.

Solución:

Verifica el estado de la cola:

openclaw queue status

Si la cola tiene más de 50 mensajes, aumenta la concurrencia:

openclaw config set --max-concurrent-requests 10

Esto procesa 10 mensajes simultáneamente en lugar de los 3 predeterminados.

Verifica la latencia de red a tu proveedor de IA:

# Anthropic
ping api.anthropic.com

# OpenAI
ping api.openai.com

Si la latencia es alta (>200ms), considera usar un proveedor diferente o un modelo local.

Habilita el tiempo de espera de solicitud:

openclaw config set --request-timeout 30000

Las solicitudes que tardan más de 30 segundos fallan y se reintentan.

El Gateway deja de responder

Problema: El Gateway deja de responder a los mensajes o llamadas a la API.

Causa: Interbloqueo, bucle infinito o agotamiento de recursos.

Solución:

Verifica el estado del Gateway:

openclaw gateway status

Si está congelado, obtén un volcado de hilos:

kill -SIGUSR1 $(pgrep -f "openclaw gateway")

Esto escribe un volcado de hilos en ~/.openclaw/gateway.log. Busca operaciones atascadas.

Reinicia el Gateway:

openclaw gateway restart

Habilita las comprobaciones de estado:

openclaw config set --health-check-interval 60

El Gateway ahora verifica su propio estado cada 60 segundos y se reinicia si no responde.

Picos de uso de CPU

Problema: OpenClaw usa el 100% de la CPU constantemente.

Causa: Bucle infinito, registro excesivo o inundación de mensajes.

Solución:

Verifica qué está consumiendo CPU:

top -p $(pgrep -f "openclaw gateway")

Reduce el nivel de registro:

openclaw config set --log-level warn

Esto deshabilita los registros de depuración e información, reduciendo la E/S.

Verifica las inundaciones de mensajes:

openclaw stats --messages --period 1h

Si estás recibiendo más de 1000 mensajes por hora, habilita la limitación de tasa por canal:

openclaw channels config whatsapp --rate-limit 100 --rate-window 3600

El Gateway se bloquea y se reinicia

El Gateway se bloquea al inicio

Problema: openclaw gateway se bloquea inmediatamente sin mensaje de error.

Causa: Archivo de configuración corrupto o dependencias faltantes.

Solución:

Ejecuta en modo depuración:

openclaw gateway --debug

Esto muestra mensajes de error detallados.

Causas comunes:

  1. Configuración corrupta: Haz una copia de seguridad y restablece la configuración.
cp ~/.openclaw/config.json ~/.openclaw/config.json.backup
openclaw config reset
openclaw onboard
  1. Dependencias faltantes: Reinstala OpenClaw.
npm uninstall -g openclaw
npm install -g openclaw@latest
  1. Puerto ya en uso: Cambia el puerto.
openclaw gateway --port 18790

El Gateway se bloquea durante la operación

Problema: El Gateway se ejecuta durante un tiempo y luego se bloquea inesperadamente.

Causa: Excepción no manejada, fuga de memoria o proceso externo que lo termina.

Solución:

Verifica los registros de fallos:

tail -100 ~/.openclaw/gateway.log

Busca rastros de pila o mensajes de error antes del fallo.

Habilita los volcados de fallos:

openclaw config set --enable-crash-dumps true

El siguiente fallo escribirá un volcado en ~/.openclaw/crashes/. Comparte esto con el equipo de OpenClaw para depuración.

Ejecuta el Gateway con reinicio automático:

openclaw gateway --auto-restart

El Gateway se reinicia automáticamente después de los fallos.

Para producción, usa un gestor de procesos:

# Usando pm2
npm install -g pm2
pm2 start openclaw -- gateway
pm2 save
pm2 startup

Datos de sesión perdidos después del reinicio

Problema: Las conversaciones se reinician después de que el Gateway se reinicia.

Causa: Las sesiones no se persisten en el disco o el archivo de sesión está corrupto.

Solución:

Habilita la persistencia de sesión:

openclaw config set --persist-sessions true --session-file ~/.openclaw/sessions.db

Las sesiones ahora se guardan en el disco cada 30 segundos.

Verifica el archivo de sesión:

ls -lh ~/.openclaw/sessions.db

Si está en 0 bytes o falta, las sesiones no se están guardando. Verifica el espacio en disco:

df -h ~

Si el disco está lleno, libera espacio y reinicia el Gateway.

Restaura desde una copia de seguridad:

cp ~/.openclaw/sessions.db.backup ~/.openclaw/sessions.db
openclaw gateway restart

Problemas específicos de la plataforma

macOS: "openclaw" no se puede abrir

Problema: macOS bloquea OpenClaw con la advertencia de "desarrollador no identificado".

Causa: Característica de seguridad Gatekeeper de macOS.

Solución:

Permitir OpenClaw:

xattr -d com.apple.quarantine $(which openclaw)

O ve a Configuración del Sistema → Privacidad y Seguridad y haz clic en "Permitir de todos modos" junto a la advertencia de OpenClaw.

Linux: Permiso denegado para inotify

Problema: "ENOSPC: Límite del sistema para el número de observadores de archivos alcanzado."

Causa: Linux limita el número de archivos que un proceso puede observar.

Solución:

Aumenta el límite:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Reinicia OpenClaw:

openclaw gateway restart

Windows: Comando no encontrado

Problema: El comando openclaw no es reconocido en Windows.

Causa: El directorio bin global de npm no está en la variable de entorno PATH.

Solución:

Encuentra el directorio global de npm:

npm config get prefix

Agrégalo a PATH:

  1. Abre Propiedades del Sistema → Variables de Entorno.
  2. Edita "Path" bajo Variables de usuario.
  3. Agrega C:\Users\TuUsuario\AppData\Roaming\npm (o la ruta obtenida anteriormente).
  4. Haz clic en Aceptar y reinicia tu terminal.

Verifica:

openclaw --version

Docker: Problemas de red

Problema: OpenClaw en Docker no puede conectarse a plataformas de mensajería.

Causa: Aislamiento de red de Docker.

Solución:

Ejecuta con la red del host:

docker run --network host openclaw/openclaw gateway

O expone el puerto del Gateway:

docker run -p 18789:18789 openclaw/openclaw gateway

Para WhatsApp, necesitas exponer puertos adicionales para el escaneo de códigos QR:

docker run -p 18789:18789 -p 3000:3000 openclaw/openclaw gateway

Herramientas de depuración y registros

Habilitar el registro de depuración

Obtén registros detallados:

openclaw config set --log-level debug
openclaw gateway restart

Los registros van a ~/.openclaw/gateway.log por defecto.

Observa los registros en tiempo real:

tail -f ~/.openclaw/gateway.log

Probar componentes individuales

Prueba los canales:

openclaw channels test whatsapp
openclaw channels test telegram
openclaw channels test discord

Prueba los agentes:

openclaw agents test default --message "Hello"

Prueba el enrutamiento:

openclaw routing test --channel whatsapp --sender +1234567890 --message "debug issue"

Inspeccionar el estado del Gateway

Obtén el estado actual:

openclaw gateway inspect

Esto muestra:

Exportar diagnósticos

Genera un informe de diagnóstico:

openclaw diagnostics export > openclaw-diagnostics.json

Esto incluye:

Comparte esto con soporte al informar problemas.

Depuración de red

Prueba la conectividad con los proveedores de IA:

openclaw network test anthropic
openclaw network test openai

Esto verifica:

Si alguna comprobación falla, tienes un problema de red.

Preguntas frecuentes

¿Por qué OpenClaw usa tanta memoria?

OpenClaw mantiene el historial de la sesión en memoria para un acceso rápido. Cada sesión almacena el contexto completo de la conversación. Si tienes 100 sesiones activas con 50 mensajes cada una, eso son 5000 mensajes en memoria.

Reduce el uso de memoria:

  1. Disminuye el tiempo de espera de la sesión.
  2. Habilita la limpieza automática.
  3. Limita la longitud del contexto por sesión.
openclaw config set --session-timeout 1800 --auto-cleanup true --max-context-length 50

¿Puedo ejecutar OpenClaw sin internet?

Sí, si usas un modelo de IA local. Instala Ollama y configura OpenClaw para usarlo:

# Instalar Ollama
curl https://ollama.ai/install.sh | sh

# Descargar un modelo
ollama pull llama2

# Configurar OpenClaw
openclaw agents add local --provider ollama --model llama2 --endpoint http://localhost:11434

Las plataformas de mensajería aún necesitan internet, pero la inferencia de IA se ejecuta localmente.

¿Cómo migro a una nueva máquina?

Exporta tu configuración:

openclaw config export > openclaw-backup.json

Copia openclaw-backup.json a la nueva máquina.

Instala OpenClaw:

npm install -g openclaw@latest

Importa la configuración:

openclaw config import openclaw-backup.json

Vuelve a conectar los canales (los códigos QR y los tokens no se transfieren):

openclaw channels login whatsapp
openclaw channels update telegram --token YOUR_TOKEN

¿Por qué los mensajes llegan fuera de orden?

OpenClaw procesa los mensajes concurrentemente. Si envías 3 mensajes rápidamente, podrían llegar al proveedor de IA en diferentes órdenes dependiendo de la sincronización de la red.

Habilita el procesamiento secuencial:

openclaw config set --max-concurrent-requests 1

Esto procesa un mensaje a la vez, preservando el orden. Es más lento pero garantiza la secuencia.

¿Puedo usar OpenClaw para producción?

Sí, pero sigue estas directrices:

  1. Ejecútalo en un servidor, no en una laptop.
  2. Usa un gestor de procesos (pm2, systemd).
  3. Habilita la persistencia de sesión.
  4. Configura monitoreo y alertas.
  5. Configura límites de tasa.
  6. Usa un proxy inverso (nginx) para la interfaz de usuario de control.
  7. Habilita HTTPS.
  8. Haz copias de seguridad de la configuración regularmente.

Ejemplo de servicio systemd:

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/bin/openclaw gateway --port 18789
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

¿Cómo informo de errores?

  1. Genera diagnósticos:
openclaw diagnostics export > diagnostics.json
  1. Abre un problema en GitHub.
  2. Incluye:

Conclusión

La mayoría de los problemas de OpenClaw provienen de problemas de red, configuración incorrecta o peculiaridades específicas de la plataforma. Esta guía cubre los 15 errores más comunes y sus soluciones.

Pasos clave para la resolución de problemas:

  1. Primero, verifica los registros (~/.openclaw/gateway.log).
  2. Prueba los componentes individualmente (canales, agentes, enrutamiento).
  3. Habilita el modo de depuración para errores detallados.
  4. Usa herramientas de diagnóstico para exportar el estado.
  5. Únete a la comunidad para obtener ayuda.

Si estás construyendo flujos de trabajo de API junto con OpenClaw, consulta Apidog para el diseño, prueba y documentación de API. Complementa la interfaz conversacional de OpenClaw con una gestión estructurada de API.

button

Próximos pasos:

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar