OpenClaw
Solución de problemas15 min de lectura

Errores Comunes de OpenClaw y Como Solucionarlos

Guia completa para diagnosticar y solucionar errores comunes de OpenClaw incluyendo problemas de instalacion, errores de API, problemas de canales y problemas de rendimiento.

O

OpenClaw Guides

Tutorial Authors

Diagnostico Rapido

Antes de profundizar en errores especificos, ejecuta estos diagnosticos:

bash
# Verificar estado general
openclaw status

# Validar configuracion
openclaw config validate

# Revisar logs por errores recientes
openclaw logs --tail 50 --level error

# Ejecutar verificacion de salud
openclaw doctor

Errores de Instalacion

Error: "Node.js version too old"

Error: OpenClaw requires Node.js >= 22.0.0
Current version: 18.17.0

Solucion:

bash
# Usando nvm (recomendado)
nvm install 22
nvm use 22
nvm alias default 22

# O usando Homebrew (macOS)
brew install node@22

# Verificar
node --version  # Deberia mostrar v22.x.x

Error: "EACCES permission denied"

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Solucion: No uses sudo. En su lugar, corrige los permisos de npm:

bash
# Opcion 1: Usar nvm (recomendado)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Opcion 2: Cambiar el directorio predeterminado de npm
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Luego reinstalar
npm install -g openclaw@latest

Error: "Cannot find module"

Error: Cannot find module '@openclaw/core'

Solucion:

bash
# Limpiar cache de npm y reinstalar
npm cache clean --force
npm uninstall -g openclaw
npm install -g openclaw@latest

# O usar el script de instalacion
curl -fsSL https://openclaw.ai/install.sh | bash

Error: "gyp ERR! build error" (Modulos nativos)

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

Solucion: Instala las herramientas de compilacion:

bash
# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential python3

# Windows
npm install -g windows-build-tools

Errores de API y Autenticacion

Error: "401 Unauthorized"

Error: API request failed with status 401: Invalid API key

Solucion:

bash
# Verificar que tu clave API este configurada
openclaw config get api-key

# Si esta vacia o incorrecta, configurala nuevamente
openclaw config set api-key

# Verifica el formato de la clave (las claves de Anthropic comienzan con sk-ant-)
# Asegurate de que no haya espacios extra o comillas

Error: "429 Rate Limited"

Error: Rate limit exceeded. Please retry after 60 seconds.

Solucion:

json
// ~/.openclaw/openclaw.json
{
  "model": {
    "rateLimiting": {
      "retryOnRateLimit": true,
      "maxRetries": 3,
      "retryDelay": 5000,
      "maxRequestsPerMinute": 30
    }
  }
}

Para limitacion de tasa persistente, considera actualizar tu nivel de API o usar un modelo diferente:

bash
openclaw config set default-model claude-3-5-haiku

Error: "402 Payment Required"

Error: API request failed: Insufficient credits

Solucion:

  1. Verifica el saldo de tu proveedor de API
  2. Agrega creditos a tu cuenta
  3. O configura limites de uso:
json
// ~/.openclaw/openclaw.json
{
  "model": {
    "quotas": {
      "daily": {
        "enabled": true,
        "maxTokens": 100000,
        "warningThreshold": 80000
      }
    }
  }
}

Error: "Connection Refused" a la API

Error: connect ECONNREFUSED api.anthropic.com:443

Solucion:

bash
# Verificar conexion a internet
ping api.anthropic.com

# Verificar si estas detras de un proxy
echo $HTTP_PROXY
echo $HTTPS_PROXY

# Configurar proxy si es necesario
openclaw config set proxy http://your-proxy:8080

# O verificar configuracion de firewall/VPN

Errores de Gateway

Error: "EADDRINUSE: Port already in use"

Error: listen EADDRINUSE: address already in use :::18789

Solucion:

bash
# Encontrar que esta usando el puerto
lsof -i :18789

# Terminar el proceso
kill -9 <PID>

# O usar un puerto diferente
openclaw gateway start --port 18790

# Actualizar config para usar nuevo puerto
openclaw config set gateway-port 18790

Error: "Gateway failed to start"

Error: Gateway failed to start: Cannot read config file

Solucion:

bash
# Validar sintaxis del archivo de configuracion
openclaw config validate

# Si esta corrupto, restablecer a valores predeterminados
openclaw config reset --confirm

# Luego reconfigurar
openclaw onboard

Error: "Gateway not responding"

bash
# Verificar si el gateway esta corriendo
openclaw status

# Si esta detenido, verificar por que
openclaw logs --tail 100

# Intentar reiniciar
openclaw gateway restart

# Si sigue fallando, verificar recursos del sistema
free -h  # Memoria
df -h    # Espacio en disco

Errores Especificos de Canales

WhatsApp: "Session expired"

Error: WhatsApp session invalid or expired

Solucion:

bash
# Re-autenticar
openclaw channel disconnect whatsapp
openclaw channel connect whatsapp
# Escanear el nuevo codigo QR

WhatsApp: "QR code not generating"

bash
# Verificar si hay otra sesion activa
pkill -f "openclaw.*whatsapp"

# Limpiar datos de sesion antiguos
rm -rf ~/.openclaw/whatsapp-session

# Intentar de nuevo
openclaw channel connect whatsapp

Telegram: "Conflict: terminated by other getUpdates"

Error: Conflict: terminated by other getUpdates request

Otra instancia esta usando el mismo token del bot.

Solucion:

bash
# Detener todas las instancias de OpenClaw
pkill -f openclaw

# Verificar otras instancias en ejecucion
ps aux | grep openclaw

# Iniciar limpio
openclaw gateway start

Discord: "Invalid token"

Error: An invalid token was provided

Solucion:

bash
# Regenerar token en el Portal de Desarrolladores de Discord
# Bot → Reset Token

# Actualizar OpenClaw
openclaw config set discord-token NUEVO_TOKEN
openclaw gateway restart

Discord: "Missing intents"

Error: Disallowed intents specified

Solucion:

  1. Ve al Portal de Desarrolladores de Discord
  2. Selecciona tu aplicacion → Bot
  3. Habilita los intents requeridos en "Privileged Gateway Intents"
  4. Guarda y reinicia OpenClaw

Errores de Memoria y Rendimiento

Error: "JavaScript heap out of memory"

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

Solucion:

bash
# Aumentar limite de memoria de Node.js
export NODE_OPTIONS="--max-old-space-size=4096"

# Agregar a tu perfil de shell para persistencia
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.bashrc

# Reiniciar OpenClaw
openclaw gateway restart

Error: "Too many open files"

Error: EMFILE: too many open files

Solucion:

bash
# Verificar limite actual
ulimit -n

# Aumentar limite (temporal)
ulimit -n 65535

# Aumentar limite (permanente - Linux)
echo "* soft nofile 65535" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65535" | sudo tee -a /etc/security/limits.conf

# macOS
sudo launchctl limit maxfiles 65535 200000

Tiempos de Respuesta Lentos

Diagnosticar:

bash
# Verificar latencia del modelo
openclaw benchmark

# Verificar recursos del sistema
openclaw stats

Solucion:

json
// ~/.openclaw/openclaw.json
{
  "model": {
    "default": "claude-3-5-haiku",
    "streaming": true,
    "maxContextTokens": 4096
  },
  "gateway": {
    "caching": {
      "enabled": true,
      "ttl": 300
    }
  }
}

Errores de Configuracion

Error: "Invalid YAML syntax"

Error: Config file has invalid YAML syntax at line 15

Solucion:

bash
# Validar YAML
openclaw config validate

# Problemas comunes:
# - Tabulaciones en lugar de espacios (usa 2 espacios)
# - Faltan dos puntos despues de las claves
# - Caracteres especiales sin comillas

# Corregir o restablecer
openclaw config edit
# o
openclaw config reset --confirm

Error: "Unknown configuration key"

Warning: Unknown configuration key 'gateway.unknownOption'

Solucion:

bash
# Verificar opciones disponibles
openclaw config list

# Eliminar claves desconocidas
openclaw config edit

Error: "Environment variable not set"

Error: Required environment variable ANTHROPIC_API_KEY is not set

Solucion:

bash
# Agregar al archivo .env
echo "ANTHROPIC_API_KEY=sk-ant-xxxxx" >> ~/.openclaw/.env

# O exportar en el shell
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# Agregar al perfil del shell para persistencia
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc

Errores de Base de Datos y Almacenamiento

Error: "Database locked"

Error: SQLITE_BUSY: database is locked

Solucion:

bash
# Detener OpenClaw
openclaw gateway stop

# Verificar archivos de bloqueo
ls -la ~/.openclaw/*.lock

# Eliminar bloqueos obsoletos
rm ~/.openclaw/*.lock

# Reiniciar
openclaw gateway start

Error: "Disk quota exceeded"

Error: ENOSPC: no space left on device

Solucion:

bash
# Verificar uso de disco
df -h

# Limpiar logs y cache de OpenClaw
openclaw cache clear
openclaw logs clear --older-than 7d

# Limpiar sesiones antiguas
rm -rf ~/.openclaw/sessions/*.old

Obtener Mas Ayuda

Habilitar Logging de Depuracion

bash
# Establecer modo de depuracion
export OPENCLAW_DEBUG=true
openclaw gateway start

# O en la configuracion
openclaw config set logLevel debug

Generar Informe de Diagnostico

bash
openclaw doctor --report > diagnostic-report.txt

Soporte de la Comunidad

Reportar un Error

Al reportar problemas, incluye:

bash
# Informacion del sistema
openclaw --version
node --version
uname -a

# Configuracion (oculta datos sensibles)
openclaw config show --redact

# Logs recientes
openclaw logs --tail 100

Siguientes Pasos