OpenClawSkills
GitHub
Gateway y Ops • 5 min de lectura

Solución de Problemas

Guía rápida de solución de problemas para fallos comunes de OpenClaw

Cuando OpenClaw se comporta mal, usa esta lista de verificación para aislar y arreglar el problema rápidamente.

Si solo quieres el flujo de triaje más corto, ver los primeros 60 segundos del FAQ. Esta página va más profundo: fallos de runtime, diagnósticos, y errores comunes.

Atajos específicos por canal: /channels/troubleshooting

Tutorial.step

Estado y Diagnósticos

Puntos de control de triaje rápido:

  • Logs de archivo del Gateway (estructurados): /tmp/openclaw/openclaw-YYYY-MM-DD.log (o logging.file).
  • Logs del servicio Gateway (supervisor):

    macOS: $OPENCLAW_STATE_DIR/logs/gateway.log + gateway.err.log (predeterminado ~/.openclaw/logs/...; perfiles usan ~/.openclaw-<perfil>/logs/...).

    Linux: journalctl --user -u openclaw-gateway[-<perfil>].service -n 200 --no-pager

    Windows: schtasks /Query /TN "OpenClaw Gateway (<perfil>)" /V /FO LIST

  • Archivos de sesión: $OPENCLAW_STATE_DIR/agents/<agentId>/sessions/
  • Caché de medios: $OPENCLAW_STATE_DIR/media/
  • Credenciales: $OPENCLAW_STATE_DIR/credentials/
Tutorial.step

Verificación de Salud

Bash
openclaw gateway status

openclaw gateway status --deep


openclaw health --json

openclaw health --verbose


lsof -nP -iTCP:18789 -sTCP:LISTEN


openclaw logs --follow

tail -20 /tmp/openclaw/openclaw-*.log
Tutorial.step

Reset Completo

Opción nuclear:

Bash
openclaw gateway stop



trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
openclaw channels login         # Re-pair WhatsApp
openclaw gateway restart           # Or: openclaw gateway

Advertencia: Esto elimina todas las sesiones y necesitarás volver a emparejar WhatsApp.

Tutorial.step

Obteniendo Ayuda

  1. Revisa los logs primero: por defecto en /tmp/openclaw/ (openclaw-YYYY-MM-DD.log o tu logging.file configurado).
  2. Busca issues existentes en GitHub.
  3. Al abrir un nuevo issue, incluye:
    • Versión de OpenClaw
    • Fragmentos de log relevantes
    • Pasos para reproducir
    • Tu configuración (¡redacta secrets!)

"¿Has intentado apagarlo y encenderlo de nuevo?" — cada persona de IT

Tutorial.step

El navegador no inicia (Linux)

Si ves "Failed to start Chrome CDP on port 18800":

Causa más probable: En Ubuntu, estás usando Chromium empaquetado con Snap.

Corrección rápida: instala Google Chrome:

Bash
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

Y establece en la configuración:

Json
{
  "browser": {
    "executablePath": "/usr/bin/google-chrome-stable"
  }
}

Guía completa: ver /reference/tools/browser-linux-troubleshooting