🦞 OpenClaw: WhatsApp + Multi-Provider Failover — Nunca Más Offline

Si usas OpenClaw para tener un agente de IA accesible por WhatsApp, sabes que la experiencia es increíble... hasta que deja de funcionar. Un reinicio del gateway, un token expirado, un DNS que falla — y de repente tu agente está muerto y nadie te avisa.

En este post te explico cómo configuré mi setup para que sea prácticamente indestructible: reconexión automática de WhatsApp, un watchdog que revisa cada 15 minutos, y 4 proveedores de modelo en cadena de failover para que si uno se cae, el siguiente entre inmediatamente.

1. El Problema

Todo empezó cuando noté que mi agente de OpenClaw había dejado de responder por WhatsApp. Le mandaba mensajes y nada. Silencio absoluto.

Al revisar los logs, encontré dos errores que se estaban encadenando:

[ERROR] WhatsApp channel disconnected
  reason: getaddrinfo ENOTFOUND web.whatsapp.com
  at: 2026-02-13T08:42:17.003Z
  retry_count: 3
  status: STOPPED

[ERROR] Model provider failed: github-copilot/claude-opus-4.6
  status: 403 Forbidden
  message: "Token expired or revoked"
  fallback: none configured

O sea: doble falla. El canal de comunicación muerto Y el proveedor de modelo muerto. Sin fallback. Sin watchdog. Sin recuperación automática. Un desastre.

2. Diagnóstico

Antes de arreglar nada, hay que entender qué pasó. OpenClaw tiene comandos muy útiles para diagnosticar el estado de todo el sistema.

Revisar el estado de los canales

openclaw channels status

Esto muestra el estado de cada canal conectado. En mi caso, WhatsApp aparecía como STOPPED:

Channel      Status      Last Activity         Uptime
─────────    ────────    ──────────────────    ──────
whatsapp     STOPPED     2026-02-13 08:42      0s
terminal     CONNECTED   2026-02-14 10:15      1d 2h

Revisar los logs del canal

openclaw channels logs --channel whatsapp --tail 50

Aquí es donde encontré los errores de DNS que mencioné arriba. Los logs te dan el detalle completo de qué pasó y cuándo.

Health check general

openclaw health

Component          Status    Details
──────────         ──────    ───────
Gateway            ✔ OK     pid: 48291, uptime: 1d 2h
WhatsApp Channel   ✘ FAIL   STOPPED - ENOTFOUND web.whatsapp.com
Model: openai      ✔ OK     gpt-5.3-codex responding
Model: copilot     ✘ FAIL   403 Forbidden - token expired
Node.js            ✔ OK     v22.14.0
Cron               ✔ OK     0 active jobs

3. Solución 1: Reconectar WhatsApp

Lo primero es lo primero: restaurar la conexión del canal de WhatsApp.

Paso 1: Re-autenticar el canal

openclaw channels login --channel whatsapp

Esto regenera la sesión de WhatsApp. Te va a pedir escanear un código QR desde tu teléfono (igual que WhatsApp Web). Una vez escaneado, la sesión queda activa.

Paso 2: Reiniciar el gateway

openclaw gateway restart

El gateway es el proceso que mantiene las conexiones activas. Al reiniciarlo, se reconectan todos los canales con las sesiones actualizadas.

Gateway restarting...
  WhatsApp: reconnecting... ✔ CONNECTED
  Terminal: reconnecting... ✔ CONNECTED
Gateway ready (pid: 51023)

Paso 3: Verificar

openclaw channels status

Channel      Status       Last Activity         Uptime
─────────    ─────────    ──────────────────    ──────
whatsapp     CONNECTED    2026-02-14 10:30      2m
terminal     CONNECTED    2026-02-14 10:30      1d 2h

4. Solución 2: Watchdog Automático (Cron)

La idea es simple: un cron job que corre cada 15 minutos, revisa si WhatsApp está conectado, y si no lo está, lo reconecta automáticamente. Lo mejor es que OpenClaw tiene esto integrado — no necesitas crontab del sistema ni scripts externos.

Crear el watchdog

openclaw cron add \
  --name "whatsapp-watchdog" \
  --every 15m \
  --message "Revisa el estado del canal de WhatsApp. Si está desconectado o stopped, ejecuta 'openclaw gateway restart' para reconectarlo." \
  --channel whatsapp \
  --to "+52XXXXXXXXXX" \
  --best-effort-deliver

¿Qué hace esto exactamente?

• --every 15m — Se ejecuta cada 15 minutos.
• --message — Le dice al agente qué hacer. El agente usa sus tools para verificar el estado y tomar acción.
• --channel whatsapp — El contexto del canal a monitorear.
• --to "+52XXXXXXXXXX" — Número de destino para las notificaciones.
• --best-effort-deliver — Si no puede entregar el mensaje (porque WhatsApp está caído), no falla el cron — simplemente lo intenta y sigue adelante.

Verificar que el cron está activo

openclaw cron list

Name                  Interval    Next Run              Channel     Status
────────────────      ────────    ──────────────────    ─────────   ──────
whatsapp-watchdog     15m         2026-02-14 10:45      whatsapp    ACTIVE

5. Solución 3: Multi-Provider Failover

El canal ya se reconecta solo. Pero ¿qué pasa si el modelo falla? Si tu único proveedor es GitHub Copilot y el token expira, el agente recibe mensajes pero no puede responder. Necesitamos un plan B. Y un plan C. Y un plan D.

La cadena de failover

La lógica es: si el proveedor primario falla (timeout, 403, 500, rate limit), OpenClaw automáticamente intenta el siguiente en la lista. Si ese también falla, pasa al siguiente. Así sucesivamente hasta que uno responda.

Configurar los fallbacks

openclaw config set agents.defaults.model.fallbacks \
  '["github-copilot/claude-opus-4.6","copilot-proxy/claude-sonnet-4.5","anthropic/claude-sonnet-4-5-20250929"]' \
  --json

✔ Config updated: agents.defaults.model.fallbacks
   [0] github-copilot/claude-opus-4.6
   [1] copilot-proxy/claude-sonnet-4.5
   [2] anthropic/claude-sonnet-4-5-20250929

6. Configurar GitHub Copilot como Provider

Para que OpenClaw pueda usar modelos vía GitHub Copilot, necesitas autenticarte con el device flow de GitHub:

openclaw models auth login-github-copilot

🔐 GitHub Copilot Authentication
   Open this URL in your browser:
   → https://github.com/login/device

   Enter this code: ABCD-1234

   Waiting for authorization...

El proceso es:

1. Abre https://github.com/login/device en tu navegador.
2. Ingresa el código que te muestra la terminal.
3. Autoriza el acceso.
4. La terminal detecta la autorización automáticamente.

   ✔ Authenticated as @oscarcode9
   Token stored securely.
   Available models: claude-opus-4.6, claude-sonnet-4.5, gpt-4o, o1...

7. Configurar Claude Code como Provider

Esta es la parte más elegante del setup. OpenClaw puede leer las credenciales de Claude Code directamente desde el macOS Keychain. Si ya tienes Claude Code instalado y autenticado, no necesitas configurar tokens ni API keys manualmente.

Lo único que necesitas hacer es decirle a OpenClaw que ese modelo existe como opción:

openclaw config set agents.defaults.models.anthropic/claude-sonnet-4-5-20250929 '{}' --json

✔ Config updated: agents.defaults.models.anthropic/claude-sonnet-4-5-20250929
   Auth: macOS Keychain (Claude Code-credentials) ✔
   Model: claude-sonnet-4-5-20250929
   Status: ready

Eso es todo. El {} vacío significa “usa las credenciales que ya tienes”. OpenClaw detecta el Keychain, extrae el token, y lo usa cuando necesita hacer requests a la API de Anthropic.

8. Instalar Node.js del Sistema

El gateway de OpenClaw corre sobre Node.js. Si estás usando la versión que viene con algún version manager (nvm, fnm, etc.), puede haber problemas de estabilidad cuando el gateway se ejecuta como proceso de fondo — especialmente después de reinicios del sistema.

La solución es instalar Node.js directamente con Homebrew para que esté disponible a nivel de sistema:

brew install node

Después, ejecuta el doctor de OpenClaw para que detecte y use la instalación del sistema:

openclaw doctor --fix

🔍 Running diagnostics...

  Node.js        ✔  v22.14.0 (/opt/homebrew/bin/node)
  npm            ✔  v10.9.2
  Gateway        ✔  running (pid: 51023)
  WhatsApp       ✔  CONNECTED
  Models         ✔  4 configured (1 primary + 3 fallbacks)
  Cron           ✔  1 active job
  Keychain       ✔  Claude Code-credentials found

✔ All checks passed. No fixes needed.

9. Verificar Todo

Ya tenemos todo configurado. Ahora hay que probar que cada proveedor funciona y que el canal de WhatsApp entrega los mensajes correctamente.

Probar el envío por WhatsApp

openclaw agent \
  -m "Responde con: Soy [provider] y estoy funcionando" \
  --to "+52XXXXXXXXXX" \
  --channel whatsapp \
  --deliver

Si todo está bien, deberías recibir un mensaje en WhatsApp con el nombre del proveedor que respondió.

Verificar la configuración de modelos

openclaw models list

Role          Provider                Model                              Status
──────────    ──────────────────      ─────────────────────────────      ──────
default       openai-codex            gpt-5.3-codex                      ✔ OK
fallback#1    github-copilot          claude-opus-4.6                    ✔ OK
fallback#2    copilot-proxy           claude-sonnet-4.5                  ✔ OK
fallback#3    anthropic               claude-sonnet-4-5-20250929         ✔ OK

Los 4 proveedores deben mostrar OK. Si alguno muestra error, revisa la autenticación de ese proveedor específico.

Probar el failover manualmente

Para verificar que el failover funciona, puedes forzar una falla temporal en el proveedor primario:

# Deshabilitar temporalmente el proveedor primario
openclaw config set agents.defaults.model.enabled false

# Enviar un mensaje — debería usar fallback#1
openclaw agent -m "¿Qué modelo me está respondiendo?" --to "+52XXXXXXXXXX" --channel whatsapp --deliver

# Re-habilitar el proveedor primario
openclaw config set agents.defaults.model.enabled true

10. Resultado Final

Aquí está el diagrama completo del flujo de failover:

Resumen de lo que configuramos

Con esta configuración, el agente puede sobrevivir:

• Caída de WhatsApp — el watchdog lo reconecta en 15 minutos máximo.
• Token de Copilot expirado — usa el siguiente proveedor en la cadena.
• Rate limit de OpenAI — pasa a Copilot automáticamente.
• Caída total de Copilot — usa Anthropic directo vía Claude Code credentials.
• Reinicio del sistema — Node.js del sistema + gateway que se restaura.

El único escenario que no está cubierto es si los 4 proveedores fallan al mismo tiempo. Spoiler: sí pasó. Sigue leyendo.

11. Post-Mortem: Cuando el Failover No Failoverea

Plot twist: después de configurar todo lo anterior, el bot se volvió a caer. Le mandaba mensajes por WhatsApp y respondía "Connection error." como texto literal. La cadena de failover estaba configurada... pero no funcionaba.

¿Qué pasó?

El problema fue que configuramos el modelo de Anthropic en openclaw.json (la config global), pero nunca copiamos las credenciales al archivo de autenticación del agente. OpenClaw separa la configuración de modelos de la autenticación:

• openclaw.json — Define qué modelos existen y cuál es el primary/fallback.
• agents/main/agent/auth-profiles.json — Contiene los tokens/credenciales reales que el agente usa para autenticarse con cada proveedor.

OpenAI y GitHub Copilot sí tenían sus credenciales ahí. Anthropic no. Entonces cuando OpenAI fallaba y GitHub Copilot estaba en cooldown por rate limit, el failover intentaba Anthropic... y también fallaba. El agente se quedaba sin opciones y respondía con el error como texto.

El fix: Registrar las credenciales de Claude Code en el agente

Las credenciales de Claude Code viven en el macOS Keychain. Hay que copiarlas al auth-profiles.json del agente para que el failover pueda usarlas:

# 1. Extraer las credenciales del Keychain
security find-generic-password -s "Claude Code-credentials" -w

Esto devuelve un JSON con accessToken, refreshToken, y expiresAt. Luego hay que agregarlos al auth-profiles:

# 2. Agregar perfil de Anthropic en auth-profiles.json
# Archivo: ~/.openclaw/agents/main/agent/auth-profiles.json
# Agregar dentro de "profiles":

"anthropic:claude-code": {
  "type": "oauth",
  "provider": "anthropic",
  "access": "sk-ant-oat01-...",   // accessToken del Keychain
  "refresh": "sk-ant-ort01-...",  // refreshToken del Keychain
  "expires": 1757037189278         // expiresAt del Keychain
}

# Y agregar en "lastGood":
"anthropic": "anthropic:claude-code"

Después de agregar las credenciales, reiniciar el gateway:

openclaw gateway restart

El otro bug: el watchdog no encontraba openclaw

El cron watchdog ejecutaba openclaw gateway restart pero fallaba con zsh:1: command not found: openclaw. El gateway corre como un proceso de fondo (LaunchAgent) y su shell no tiene el mismo PATH que tu terminal.

La solución: usar la ruta absoluta del binario en el mensaje del cron:

# Antes (fallaba en background):
"Ejecuta 'openclaw gateway restart' para reconectarlo."

# Después (funciona siempre):
"Ejecuta '/ruta/completa/a/openclaw gateway restart' para reconectarlo."

12. Checklist Final

Para asegurarte de que tu setup está completo y no te pase lo que a mí, revisa cada punto:

13. La Tormenta Perfecta: Los 3 Proveedores Cayeron a la Vez

Recuerdan que dije que si los 3 proveedores fallan al mismo tiempo “tenemos problemas más grandes”? Bueno, pasó. Horas después de publicar este post, los 3 murieron simultáneamente:

Tres fallas distintas, cada una por una razón diferente. Un rate limit, un token expirado, y un límite de plan. La combinación perfecta para dejar al bot completamente muerto.

Root cause #1: Tokens de Anthropic expirados en el Keychain

Las credenciales de Claude Code en el macOS Keychain estaban expiradas desde septiembre 2025. Claude Code funciona en memoria con tokens frescos, pero no actualiza el Keychain cuando renueva sus tokens internamente. OpenClaw lee del Keychain → obtiene tokens viejos → OAuth refresh falla → proveedor muerto.

# Verificar cuándo se modificó el Keychain:
security find-generic-password -s "Claude Code-credentials" -g 2>&1 | grep mdat
mdat=0x323032353039... (September 2025!)

Root cause #2: El cooldown exponencial en cascada

Revisé el código fuente de OpenClaw y encontré la trampa. Cuando un proveedor recibe un error 429 (rate limit), OpenClaw pone el perfil de autenticación en cooldown exponencial:

El problema: el cooldown es global por perfil. Si el gateway procesa múltiples mensajes de WhatsApp concurrentemente (o un cron job al mismo tiempo), cada request fallido incrementa el contador. En segundos, el cooldown escala de 60s a 1 hora, y todos los requests siguientes fallan instantáneamente sin siquiera intentar llamar al API.

Además, descubrí en los logs que los “rate limits” de 23 segundos en realidad eran timeouts. El API de Anthropic se colgaba (en vez de devolver 429 instantáneo), el request expiraba, y OpenClaw lo clasificaba como rate limit con el comentario en el código: // Treat timeout as potential rate limit (Antigravity hangs on rate limit).

Root cause #3: Config error que eliminó un proveedor de la cadena

Durante el debugging, cambié el modelo primario de openai-codex a anthropic para forzar pruebas directas. Esto causó que la cadena de failover pasara de 3 proveedores a 2:

# Config durante debugging (MAL):
"primary": "anthropic/claude-sonnet-4-5-20250929"    // anthropic como primario
"fallbacks": [
  "github-copilot/claude-opus-4.6",              // fallback 1
  "anthropic/claude-sonnet-4-5-20250929"          // duplicado = eliminado
]
// Resultado: solo 2 proveedores! openai-codex quedó fuera

# Config correcta:
"primary": "openai-codex/gpt-5.3-codex"               // openai como primario
"fallbacks": [
  "github-copilot/claude-opus-4.6",              // fallback 1
  "anthropic/claude-sonnet-4-5-20250929"          // fallback 2
]
// Resultado: 3 proveedores en cadena

Los logs del gateway confirmaban: All models failed (2) — no 3. OpenClaw deduplica los modelos, así que anthropic como primario + anthropic como fallback = un solo proveedor.

El fix: Tokens frescos via OAuth PKCE + restaurar la cadena

La solución tuvo 3 partes:

Parte 1: Obtener tokens frescos de Anthropic haciendo el flujo OAuth PKCE manualmente (el mismo que usa Claude Code internamente):

# 1. Generar PKCE verifier + challenge
# 2. Abrir URL de autorización en claude.ai/oauth/authorize
# 3. Copiar el código del callback
# 4. Intercambiar código por tokens frescos:
curl -X POST https://console.anthropic.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"authorization_code","code":"...","code_verifier":"...","client_id":"...","redirect_uri":"..."}'

# Resultado: access_token + refresh_token frescos (8 horas)

Parte 2: Restaurar el modelo primario a openai-codex/gpt-5.3-codex para tener los 3 proveedores en la cadena.

Parte 3: Limpiar los cooldowns acumulados en auth-profiles.json y reiniciar el gateway:

# Limpiar cooldowns (en auth-profiles.json, cambiar usageStats a vacío):
"usageStats": {}

# Reiniciar:
openclaw gateway restart

Resultado del test después del fix:

openclaw agent --session-id "test-fix" -m "di OK"
[failover] openai-codex: rate_limit (10s) → skip
[failover] github-copilot: rate_limit (22s) → skip
[failover] anthropic: ✔ success
OK

14. Lecciones del Incidente

1. El Keychain miente. Claude Code funciona en memoria con tokens frescos pero no actualiza el Keychain. Si dependes del Keychain para credenciales, verifica que no estén expiradas.
2. El cooldown exponencial es una espada de doble filo. Protege contra spam al API, pero en un escenario con múltiples requests concurrentes, un solo error escala en segundos a 1 hora de bloqueo total.
3. Nunca cambies el primary model para “debug rápido”. Si tu primary es igual a un fallback, OpenClaw deduplica y pierdes un proveedor de la cadena sin darte cuenta.
4. Los timeouts se clasifican como rate limits. Una respuesta lenta del API (23s timeout) cuenta igual que un 429 real. Esto acelera el cooldown exponencial artificialmente.
5. Limpia usageStats después de arreglar la causa raíz. Si no limpias los cooldowns acumulados, el gateway sigue rechazando requests instantáneamente incluso con tokens frescos.