Diagnostica tus canales OpenClaw: Guía de comandos CLI

¿Alguna vez has sentido que estás adivinando por qué tu conexión falló? No hay nada peor que un Gateway silencioso sin saber si el problema es la sesión, el canal o tu propia configuración. Mantener la conectividad activa no debería ser un juego de azar, y por eso contar con herramientas de diagnóstico claras es fundamental para cualquier desarrollador.

Esta guía te ayudará a verificar la conectividad de tus canales de forma directa, sin rodeos y con datos reales.

Verificaciones rápidas

• openclaw status — resumen local: accesibilidad/modo del Gateway, avisos de actualización, antigüedad de la autenticación del canal vinculado, sesiones y actividad reciente.
• openclaw status --all — diagnóstico local completo (solo lectura, con colores, seguro para pegar al depurar).
• openclaw status --deep — también sondea el Gateway en ejecución (probes por canal cuando están soportados).
• openclaw health --json — solicita al Gateway en ejecución un snapshot completo de salud (solo WS; sin socket directo de Baileys).
• Envía /status como un mensaje individual en WhatsApp/WebChat para obtener una respuesta de estado sin invocar al agente.
• Logs: usa tail en /tmp/openclaw/openclaw-*.log y filtra por web-heartbeat, web-reconnect, web-auto-reply, web-inbound.

Diagnóstico profundo

• Credenciales en disco: ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json (el mtime debería ser reciente).
• Almacén de sesiones: ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json (la ruta se puede sobrescribir en la configuración). El conteo y los destinatarios recientes se muestran mediante status.
• Flujo de revinculación: openclaw channels logout && openclaw channels login --verbose cuando aparezcan códigos de estado 409–515 o loggedOut en los logs. (Nota: el flujo de inicio de sesión por QR se reinicia automáticamente una vez para el estado 515 tras el emparejamiento).

Configuración del monitor de estado

• gateway.channelHealthCheckMinutes: cada cuánto tiempo el Gateway verifica la salud del canal. Por defecto: 5. Configura 0 para desactivar los reinicios del monitor de salud globalmente.
• gateway.channelStaleEventThresholdMinutes: cuánto tiempo puede estar inactivo un canal conectado antes de que el monitor de salud lo considere estancado y lo reinicie. Por defecto: 30. Mantén este valor mayor o igual a gateway.channelHealthCheckMinutes.
• gateway.channelMaxRestartsPerHour: límite rodante de una hora para reinicios del monitor de salud por canal/cuenta. Por defecto: 10.
• channels.<provider>.healthMonitor.enabled: desactiva los reinicios del monitor de salud para un canal específico mientras mantienes activa la monitorización global.
• channels.<provider>.accounts.<accountId>.healthMonitor.enabled: sobrescritura multi-cuenta que prevalece sobre la configuración a nivel de canal.
• Estas sobrescrituras por canal se aplican a los monitores de canal integrados que las exponen actualmente: Discord, Google Chat, iMessage, Microsoft Teams, Signal, Slack, Telegram y WhatsApp.

Cuando algo falla

• logged out o estado 409–515 → vuelve a vincular con openclaw channels logout y luego openclaw channels login.
• Gateway inalcanzable → inícialo: openclaw gateway --port 18789 (usa --force si el puerto está ocupado).
• Sin mensajes entrantes → confirma que el teléfono vinculado esté online y que el remitente esté permitido (channels.whatsapp.allowFrom); para chats grupales, asegúrate de que la lista de permitidos y las reglas de mención coincidan (channels.whatsapp.groups, agents.list[].groupChat.mentionPatterns).

Comando “health” dedicado

openclaw health --json solicita al Gateway en ejecución su snapshot de salud (sin sockets de canal directos desde la CLI). Informa sobre la antigüedad de las credenciales/autenticación vinculadas cuando están disponibles, resúmenes de sondeo por canal, resumen del almacén de sesiones y la duración del sondeo. Sale con un código no cero si el Gateway es inalcanzable o si el sondeo falla o agota el tiempo de espera.

Opciones:

• --json: salida JSON legible por máquinas
• --timeout <ms>: sobrescribe el tiempo de espera por defecto de 10s para el sondeo
• --probe: fuerza un sondeo en vivo de todos los canales en lugar de devolver el snapshot de salud en caché

El snapshot de salud incluye: ok (booleano), ts (timestamp), durationMs (tiempo de sondeo), estado por canal, disponibilidad del agente y resumen del almacén de sesiones.

Siguientes pasos:

• Configuración de canales
• Gestión de agentes

AI Setup Assistant