Gestiona logs de OpenClaw: monitoreo y configuración

¿Alguna vez has pasado horas intentando adivinar por qué un mensaje no llega o por qué un Gateway se comporta de forma extraña? Sin visibilidad, estás trabajando a ciegas. Tener un sistema de logs bien configurado no es solo una buena práctica, es lo que te permite solucionar problemas en minutos en lugar de perder toda la tarde.

OpenClaw registra información en dos lugares:

• File logs (líneas JSON) escritos por el Gateway.
• Console output que ves en las terminales y en la Control UI.

En esta guía verás dónde están los logs, cómo leerlos y cómo configurar los niveles y formatos.

Dónde viven los logs

Por defecto, el Gateway escribe un archivo de log rotativo en:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

La fecha utiliza la zona horaria local del host del Gateway.

Puedes cambiar esta ruta en ~/.openclaw/openclaw.json:

{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}

Cómo leer los logs

CLI: live tail (recomendado)

Usa la CLI para seguir el archivo de log del Gateway en tiempo real a través de RPC:

openclaw logs --follow

Modos de salida:

• Sesiones TTY: líneas de log estructuradas, con colores y formato amigable.
• Sesiones Non-TTY: texto plano.
• --json: JSON delimitado por líneas (un evento de log por línea).
• --plain: fuerza el texto plano en sesiones TTY.
• --no-color: desactiva los colores ANSI.

En el modo JSON, la CLI emite objetos etiquetados por type:

• meta: metadatos del stream (archivo, cursor, tamaño)
• log: entrada de log procesada
• notice: avisos de truncado o rotación
• raw: línea de log sin procesar

Si el Gateway no responde, la CLI te sugerirá ejecutar:

openclaw doctor

Control UI (web)

La pestaña Logs de la Control UI hace un tail del mismo archivo usando logs.tail. Consulta /web/control-ui para saber cómo abrirla.

Logs exclusivos de canales

Para filtrar la actividad de canales específicos (WhatsApp, Telegram, etc.), usa:

openclaw channels logs --channel whatsapp

Formatos de log

File logs (JSONL)

Cada línea en el archivo de log es un objeto JSON. La CLI y la Control UI procesan estas entradas para mostrar una salida estructurada (tiempo, nivel, subsistema, mensaje).

Console output

Los logs de la consola detectan si hay una TTY activa y tienen un formato optimizado para la lectura:

• Prefijos de subsistema (ej. gateway/channels/whatsapp)
• Colores por nivel (info/warn/error)
• Modo compacto o JSON opcional

El formato de la consola se controla mediante logging.consoleStyle.

Configuración de logging

Toda la configuración de logs reside bajo la clave logging en ~/.openclaw/openclaw.json.

{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

Niveles de log

• logging.level: nivel para los file logs (JSONL).
• logging.consoleLevel: nivel de verbosidad de la consola.

Puedes sobrescribir ambos con la variable de entorno OPENCLAW_LOG_LEVEL (ej. OPENCLAW_LOG_LEVEL=debug). La variable de entorno tiene prioridad sobre el archivo de configuración, así que puedes subir la verbosidad para una ejecución específica sin editar openclaw.json. También puedes usar la opción global de la CLI --log-level <level> (por ejemplo, openclaw --log-level debug gateway run), que sobrescribe la variable de entorno para ese comando.

Ten en cuenta que --verbose solo afecta a la salida de la consola; no cambia los niveles de los logs en archivo.

Estilos de consola

logging.consoleStyle:

• pretty: legible para humanos, con colores y timestamps.
• compact: salida más ajustada (ideal para sesiones largas).
• json: un JSON por línea (para procesadores de logs).

Redacción de datos sensibles

Los resúmenes de herramientas pueden ocultar tokens sensibles antes de que lleguen a la consola:

• logging.redactSensitive: off | tools (por defecto: tools)
• logging.redactPatterns: lista de strings regex para personalizar qué se oculta

La redacción afecta solo a la salida de consola y no modifica los logs en archivo.

Diagnósticos + OpenTelemetry

Los diagnósticos son eventos estructurados y legibles por máquinas para ejecuciones de modelos y telemetría del flujo de mensajes (webhooks, colas, estado de sesión). No reemplazan a los logs; existen para alimentar métricas, trazas y otros exportadores.

Los eventos de diagnóstico se emiten internamente, pero los exportadores solo se conectan cuando los diagnósticos y el plugin exportador están activos.

OpenTelemetry vs OTLP

• OpenTelemetry (OTel): el modelo de datos y SDKs para trazas, métricas y logs.
• OTLP: el protocolo de red usado para exportar datos de OTel a un backend o colector.
• OpenClaw exporta actualmente vía OTLP/HTTP (protobuf).

Señales exportadas

• Métricas: contadores e histogramas (uso de tokens, flujo de mensajes, colas).
• Trazas: spans para el uso de modelos y procesamiento de webhooks/mensajes.
• Logs: exportados vía OTLP cuando diagnostics.otel.logs está habilitado. El volumen puede ser alto; vigila el logging.level y los filtros del exportador.

Catálogo de eventos de diagnóstico

Uso del modelo:

• model.usage: tokens, coste, duración, contexto, provider/model/channel, IDs de sesión.

Flujo de mensajes:

• webhook.received: ingreso de webhook por canal.
• webhook.processed: webhook gestionado y su duración.
• webhook.error: errores en el handler del webhook.
• message.queued: mensaje encolado para procesamiento.
• message.processed: resultado, duración y error opcional.

Cola y sesión:

• queue.lane.enqueue: encolado en el carril de comandos y profundidad.
• queue.lane.dequeue: salida de la cola y tiempo de espera.
• session.state: transición de estado de sesión y motivo.
• session.stuck: advertencia de sesión atascada y antigüedad.
• run.attempt: metadatos de reintentos de ejecución.
• diagnostic.heartbeat: contadores agregados (webhooks/cola/sesión).

Activar diagnósticos (sin exportador)

Usa esto si quieres que los eventos de diagnóstico estén disponibles para plugins o sumideros personalizados:

{
  "diagnostics": {
    "enabled": true
  }
}

Flags de diagnóstico (logs específicos)

Usa flags para activar logs de depuración adicionales y específicos sin subir el logging.level general. Los flags no distinguen entre mayúsculas y minúsculas y admiten comodines (ej. telegram.* o *).

{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}

Sobrescritura por entorno (un solo uso):

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Notas:

• Los logs de los flags van al archivo de log estándar (el mismo que logging.file).
• La salida sigue estando redactada según logging.redactSensitive.
• Guía completa: /diagnostics/flags.

Exportar a OpenTelemetry

Los diagnósticos se pueden exportar mediante el plugin diagnostics-otel (OTLP/HTTP). Esto funciona con cualquier colector o backend de OpenTelemetry que acepte OTLP/HTTP.

{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}

Notas:

• También puedes activar el plugin con openclaw plugins enable diagnostics-otel.
• protocol actualmente solo soporta http/protobuf. Se ignora grpc.
• Las métricas incluyen uso de tokens, coste, tamaño de contexto, duración de ejecución y contadores de flujo de mensajes.
• Las trazas y métricas se pueden alternar con traces / metrics (por defecto: on).
• Configura headers si tu colector requiere autenticación.
• Variables de entorno soportadas: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL.

Métricas exportadas (nombres y tipos)

Uso del modelo:

• openclaw.tokens (counter, attrs: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.cost.usd (counter, attrs: openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.run.duration_ms (histogram, attrs: openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.context.tokens (histogram, attrs: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)

Flujo de mensajes:

• openclaw.webhook.received (counter, attrs: openclaw.channel, openclaw.webhook)
• openclaw.webhook.error (counter, attrs: openclaw.channel, openclaw.webhook)
• openclaw.webhook.duration_ms (histogram, attrs: openclaw.channel, openclaw.webhook)
• openclaw.message.queued (counter, attrs: openclaw.channel, openclaw.source)
• openclaw.message.processed (counter, attrs: openclaw.channel, openclaw.outcome)
• openclaw.message.duration_ms (histogram, attrs: openclaw.channel, openclaw.outcome)

Colas y sesiones:

• openclaw.queue.lane.enqueue (counter, attrs: openclaw.lane)
• openclaw.queue.lane.dequeue (counter, attrs: openclaw.lane)
• openclaw.queue.depth (histogram, attrs: openclaw.lane o openclaw.channel=heartbeat)
• openclaw.queue.wait_ms (histogram, attrs: openclaw.lane)
• openclaw.session.state (counter, attrs: openclaw.state, openclaw.reason)
• openclaw.session.stuck (counter, attrs: openclaw.state)
• openclaw.session.stuck_age_ms (histogram, attrs: openclaw.state)
• openclaw.run.attempt (counter, attrs: openclaw.attempt)

Spans exportados (nombres y atributos clave)

• openclaw.model.usage
  • openclaw.channel, openclaw.provider, openclaw.model
  • openclaw.sessionKey, openclaw.sessionId
  • openclaw.tokens.* (input/output/cache_read/cache_write/total)
• openclaw.webhook.processed
  • openclaw.channel, openclaw.webhook, openclaw.chatId
• openclaw.webhook.error
  • openclaw.channel, openclaw.webhook, openclaw.chatId, openclaw.error
• openclaw.message.processed
  • openclaw.channel, openclaw.outcome, openclaw.chatId, openclaw.messageId, openclaw.sessionKey, openclaw.sessionId, openclaw.reason
• openclaw.session.stuck
  • openclaw.state, openclaw.ageMs, openclaw.queueDepth, openclaw.sessionKey, openclaw.sessionId

Muestreo y purga (Sampling + flushing)

• Muestreo de trazas: diagnostics.otel.sampleRate (0.0–1.0, solo spans raíz).
• Intervalo de exportación de métricas: diagnostics.otel.flushIntervalMs (mínimo 1000ms).

Notas sobre el protocolo

• Los endpoints OTLP/HTTP se pueden configurar vía diagnostics.otel.endpoint o OTEL_EXPORTER_OTLP_ENDPOINT.
• Si el endpoint ya contiene /v1/traces o /v1/metrics, se usa tal cual.
• Si el endpoint ya contiene /v1/logs, se usa tal cual para los logs.
• diagnostics.otel.logs activa la exportación de logs OTLP para la salida del logger principal.

Comportamiento de exportación de logs

• Los logs OTLP usan los mismos registros estructurados que se escriben en logging.file.
• Respetan el logging.level (nivel de log de archivo). La redacción de consola no se aplica a los logs OTLP.
• En instalaciones de alto volumen, es preferible usar el muestreo o filtrado del colector OTLP.

Consejos para solucionar problemas

• ¿El Gateway no es accesible? Ejecuta primero openclaw doctor.
• ¿Logs vacíos? Verifica que el Gateway esté corriendo y escribiendo en la ruta definida en logging.file.
• ¿Necesitas más detalle? Cambia logging.level a debug o trace e intenta de nuevo.

Relacionado

• Gateway Logging Internals — Estilos de log WS, prefijos de subsistema y captura de consola.
• Diagnostics — Exportación a OpenTelemetry y configuración de trazas de caché.

AI Setup Assistant