Resolución de problemas de OpenClaw: 20 problemas comunes resueltos

¿Te encuentras con problemas con OpenClaw? No estás solo. Esta guía cubre los 20 problemas más comunes que encuentran los usuarios, recopilados de hilos de Reddit, issues de GitHub y el Discord de la comunidad. Cada problema incluye los síntomas, la causa raíz y la solución paso a paso.

1. El agente no responde a los mensajes

Síntomas: envías un mensaje vía Telegram/correo electrónico/WhatsApp pero no obtienes respuesta. El panel de administración muestra el agente como "online".

Causa raíz: normalmente un problema de webhook o de polling del canal.

Solución:

# Check if the agent process is actually running
openclaw status

# Check channel health
openclaw channels status

# Restart the specific channel
openclaw channels restart telegram

# Check logs for errors
openclaw logs --filter "channel" --since 1h

Si el canal muestra "connected" pero los mensajes no llegan, verifica que la URL de tu webhook sea accesible públicamente y apunte al puerto correcto.

2. Falla la instalación de una skill

Síntomas: openclaw skill install skill-name finaliza con un error sobre dependencias o compilación.

Causa raíz: discrepancia en la versión de Node.js o falta de herramientas de compilación.

Solución:

# Check Node.js version (needs 20+)
node --version

# If below 20, update via nvm
nvm install 20
nvm use 20

# Install build tools if needed (Ubuntu/Debian)
sudo apt install build-essential python3

# Retry skill install with verbose output
openclaw skill install skill-name --verbose

3. Error "Model Not Found"

Síntomas: el agente responde con "Error: model not found" o "Invalid model identifier".

Causa raíz: tu clave de API no tiene acceso al modelo solicitado, o el nombre del modelo es incorrecto en la configuración.

Solución:

# Check your current model config
openclaw config get model

# List available models for your API key
openclaw models list

# Set a valid model
openclaw config set model claude-sonnet-4-20250514

Verifica que tu clave de API tenga acceso al modelo que estás solicitando. Algunos modelos (como Claude Opus) requieren un nivel de pago.

4. Uso elevado de memoria

Síntomas: el proceso de OpenClaw usa más de 1 GB de RAM y el sistema se vuelve lento.

Causa raíz: un contexto de conversación extenso, fugas de memoria en las skills o una base de datos de memoria sin límites.

Solución:

# Check current memory usage
openclaw status --resources

# Clear old conversation history
openclaw memory prune --older-than 30d

# Restart to free leaked memory
openclaw restart

# Set memory limits in config.yaml
# memory:
#   max_context_tokens: 50000
#   prune_threshold: 80000

5. El token de autenticación del canal ha caducado

Síntomas: el canal se desconecta periódicamente, los registros muestran "401 Unauthorized" o "token expired".

Causa raíz: los tokens OAuth de algunos canales caducan y necesitan renovarse.

Solución:

# Re-authenticate the channel
openclaw channels auth telegram

# For email channels, regenerate the webhook secret
openclaw channels regenerate-token email

# Verify connection
openclaw channels test telegram

Si usas Inbounter para el correo electrónico, las claves de API no caducan: comprueba que no hayas rotado accidentalmente tu clave en el panel de Inbounter.

6. El agente da respuestas incorrectas o desactualizadas

Síntomas: el agente hace referencia a información antigua o parece "olvidar" el contexto reciente.

Causa raíz: SOUL.md está desactualizado, o la base de datos de memoria está corrupta.

Solución:

# Update your SOUL.md with current information
nano ~/.openclaw/SOUL.md

# Rebuild the memory index
openclaw memory reindex

# Clear and reimport memory if corrupted
openclaw memory export > backup.json
openclaw memory clear
openclaw memory import < backup.json

7. El contenedor de Docker se reinicia constantemente

Síntomas: docker ps muestra el contenedor reiniciándose cada pocos segundos. Los registros muestran errores de arranque.

Causa raíz: normalmente un error de configuración o la falta de variables de entorno.

Solución:

# Check container logs
docker logs openclaw --tail 50

# Common causes:
# 1. Missing API key - check .env file
# 2. Permission denied on volumes - fix ownership
sudo chown -R 1000:1000 ./config ./data

# 3. Port already in use
sudo lsof -i :3080

# 4. Invalid config.yaml syntax
openclaw config validate

8. El bot de Telegram no recibe mensajes

Síntomas: el bot está online en Telegram pero no responde a los mensajes en los grupos.

Causa raíz: el modo de privacidad del bot está habilitado (por defecto en Telegram). Por defecto, los bots en grupos solo ven los comandos.

Solución:

1. Abre @BotFather en Telegram
2. Envía /mybots y selecciona tu bot
3. Ve a "Bot Settings" y luego a "Group Privacy"
4. Configúralo en "Disable" (el bot verá todos los mensajes)
5. Elimina y vuelve a añadir el bot al grupo

9. "Rate Limit Exceeded" del proveedor de LLM

Síntomas: el agente responde con errores de límite de tasa durante un uso intensivo.

Causa raíz: estás alcanzando los límites de tasa de la API del nivel de tu proveedor de LLM.

Solución:

# config.yaml - add rate limiting
llm:
  rate_limit:
    requests_per_minute: 30
    retry_delay: 5
    max_retries: 3
  fallback_model: "claude-sonnet-4-20250514"  # Cheaper model as fallback

Considera subir de nivel tu API o usar varias claves de API con balanceo de carga.

10. Las skills no se encuentran después de una actualización

Síntomas: tras actualizar OpenClaw, las skills instaladas previamente aparecen como "not found".

Causa raíz: la ruta del directorio de skills cambió entre versiones.

Solución:

# Check where skills are expected
openclaw config get skills_dir

# List actually installed skills
ls ~/.openclaw/skills/

# Re-register skills
openclaw skill scan
openclaw skill list

11. Error de base de datos bloqueada

Síntomas: errores "SQLITE_BUSY: database is locked" en los registros.

Causa raíz: varios procesos de OpenClaw accediendo a la misma base de datos, o un proceso que se bloqueó y dejó un lock.

Solución:

# Check for multiple processes
ps aux | grep openclaw

# Kill any stuck processes
openclaw stop --force

# Remove stale lock file if present
rm -f ~/.openclaw/data/openclaw.db-wal
rm -f ~/.openclaw/data/openclaw.db-shm

# Restart
openclaw start

12. Fallos en la entrega de webhooks

Síntomas: los servicios externos (correo electrónico, GitHub) no pueden alcanzar el endpoint de webhook de tu OpenClaw.

Causa raíz: un firewall bloqueando las conexiones entrantes, una URL incorrecta o problemas de SSL.

Solución:

# Test webhook endpoint locally
curl -X POST http://localhost:3080/webhook/email -d '{"test": true}'

# Check if port is accessible externally
# Use a service like https://www.whatismyip.com/ to get your public IP
# Then test from another machine or use a webhook testing service

# If behind NAT, set up port forwarding or use a tunnel
# Option 1: Tailscale Funnel
tailscale funnel 3080

# Option 2: Cloudflare Tunnel
cloudflared tunnel --url http://localhost:3080

13. El agente ejecuta comandos incorrectos

Síntomas: el agente malinterpreta las instrucciones y ejecuta comandos destructivos.

Causa raíz: orientación insuficiente en SOUL.md, o el modelo necesita instrucciones más explícitas.

Solución:

Añade barreras de seguridad a tu SOUL.md:

## Safety Rules
- NEVER run rm -rf without explicit confirmation
- NEVER modify files outside of /home/user/projects/
- Always show the command you plan to run and ask for approval
- Use --dry-run flags when available

Habilita también el modo de aprobación de comandos:

# config.yaml
safety:
  command_approval: true
  blocked_commands:
    - "rm -rf /"
    - "dd if="
    - "mkfs"

14. Errores de certificado SSL

Síntomas: "UNABLE_TO_VERIFY_LEAF_SIGNATURE" o errores de certificado al conectar con las APIs.

Causa raíz: los certificados CA del sistema están desactualizados, o estás detrás de un proxy corporativo que intercepta el SSL.

Solución:

# Update CA certificates
sudo apt update && sudo apt install ca-certificates

# If behind a proxy, add the proxy CA
export NODE_EXTRA_CA_CERTS=/path/to/proxy-ca.pem

# As a last resort (NOT recommended for production)
# export NODE_TLS_REJECT_UNAUTHORIZED=0

15. Los cron jobs no se activan

Síntomas: las tareas programadas definidas con openclaw cron no se ejecutan a la hora esperada.

Causa raíz: discrepancia de zona horaria o el servicio de cron no está en ejecución.

Solución:

# Check cron service status
openclaw cron status

# Verify timezone
openclaw config get timezone
date  # Compare system time

# Set correct timezone
openclaw config set timezone "America/New_York"

# List scheduled jobs
openclaw cron list

# Test a job manually
openclaw cron run job-name

16. El agente no puede acceder a archivos locales

Síntomas: el agente dice que no encuentra archivos que existen en tu sistema.

Causa raíz: en Docker, el archivo no está en un volumen montado. En bare metal, permiso denegado.

Solución (Docker):

# Add the directory as a volume in docker-compose.yml
volumes:
  - /home/user/documents:/documents:ro

Solución (bare metal):

# Check permissions
ls -la /path/to/file

# Fix ownership if needed
sudo chown openclaw:openclaw /path/to/file

17. El canal de correo electrónico no envía

Síntomas: el agente redacta correos pero nunca llegan.

Causa raíz: problemas de configuración SMTP, o los correos están siendo capturados por los filtros de spam.

Solución:

Si usas una configuración SMTP directa, considera cambiar a un servicio basado en API. Inbounter ofrece una API REST sencilla para enviar correos que gestiona automáticamente la entregabilidad, SPF, DKIM y DMARC:

# config.yaml
channels:
  email:
    provider: "inbounter"
    api_key: "${INBOUNTER_API_KEY}"
    from: "agent@yourdomain.com"

Esto elimina los quebraderos de cabeza de la configuración SMTP y mejora la entregabilidad.

18. La conexión de WhatsApp se cae con frecuencia

Síntomas: el canal de WhatsApp se desconecta cada pocas horas y necesita una reconexión manual.

Causa raíz: tiempo de espera agotado de la sesión de WhatsApp Web o conflicto de dispositivos.

Solución:

# Use the multi-device beta session
openclaw channels config whatsapp --multi-device

# Keep the session alive
# config.yaml
channels:
  whatsapp:
    keep_alive: true
    reconnect_delay: 10
    max_reconnect_attempts: 50

Asegúrate también de que solo haya un dispositivo conectado a la cuenta de WhatsApp.

19. Las respuestas del agente son extremadamente lentas

Síntomas: las respuestas tardan más de 30 segundos incluso para preguntas sencillas.

Causa raíz: usar un modelo caro para todas las consultas, latencia de red o una ventana de contexto demasiado grande.

Solución:

# Use a faster model for simple queries
llm:
  default_model: "claude-sonnet-4-20250514"
  complex_model: "claude-opus-4-20250514"
  routing:
    simple_queries: "default_model"
    complex_tasks: "complex_model"

# Check network latency to API provider
curl -w "Connect: %{time_connect}s\nTotal: %{time_total}s\n" \
  -o /dev/null -s https://api.anthropic.com/v1/messages

# Trim context if it is too large
openclaw memory prune --keep-recent 100

20. OpenClaw no arranca después de reiniciar el sistema

Síntomas: OpenClaw funcionaba bien pero no arranca tras reiniciar el servidor.

Causa raíz: el servicio no está habilitado para el arranque automático, o las variables de entorno no se conservan.

Solución (Docker):

# Ensure restart policy is set
# In docker-compose.yml: restart: unless-stopped
docker compose up -d

Solución (bare metal):

# Enable systemd service
sudo systemctl enable openclaw

# Check if it failed to start
sudo systemctl status openclaw
journalctl -u openclaw --since "1 hour ago"

# Common cause: environment variables not in service file
# Add EnvironmentFile to your systemd unit

Consejos generales de resolución de problemas

Cuando ninguna de las soluciones anteriores funcione:

# Run the built-in diagnostic tool
openclaw doctor

# Export a diagnostic report for support
openclaw diagnostics export > diagnostic-report.txt

# Check GitHub issues for your specific error
# https://github.com/openclaw/openclaw/issues

# Reset to clean state (back up first!)
openclaw backup create
openclaw reset --config-only

Configura una monitorización proactiva con Inbounter para recibir alertas por correo electrónico o SMS antes de que los problemas se propaguen. Configura tu agente para que envíe un latido cada 5 minutos: si el latido se detiene, sabrás que algo va mal.

Preguntas frecuentes

¿Dónde se almacenan los registros de OpenClaw?

Por defecto, los registros están en ~/.openclaw/logs/openclaw.log. En Docker, accede a ellos con docker logs openclaw.

¿Cómo restablezco OpenClaw por completo?

openclaw stop
rm -rf ~/.openclaw/data/
openclaw init
openclaw start

Esto eliminará toda la memoria, las conversaciones y los ajustes. Haz una copia de seguridad primero.

¿Puedo ejecutar OpenClaw en modo detallado?

Sí: openclaw start --verbose o configura logging.level: debug en config.yaml. Esto genera archivos de registro muy grandes, así que úsalo temporalmente solo para depurar.

¿Cómo reporto un error?

Abre un issue en GitHub con la salida de openclaw diagnostics export. Elimina cualquier clave de API o información sensible del informe antes de publicarlo.

¿Hay una comunidad de OpenClaw para pedir ayuda?

Sí. El servidor oficial de Discord y el subreddit r/openclaw son comunidades activas. Busca antes de publicar: la mayoría de los problemas comunes ya tienen soluciones.

¿Cómo compruebo qué versión estoy ejecutando?

openclaw --version

Compárala con la última versión en GitHub para ver si una actualización podría solucionar tu problema.

¿Cansado de descubrir los problemas de OpenClaw después de que ocurran? Inbounter permite que tu agente de IA envíe alertas por correo electrónico y SMS en tiempo real. Recibe una notificación en el momento en que algo va mal.