Logging

OpenClaw registra logs en dos lugares:

  • Logs en archivo (JSON lines) escritos por el Gateway.
  • Salida de consola mostrada en terminales y la interfaz de control.

Esta página explica dónde se guardan los logs, cómo leerlos y cómo configurar niveles y formatos de log.

Dónde se guardan los logs

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

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

La fecha usa la zona horaria local del host del gateway.

Puedes cambiar esto en ~/.openclaw/openclaw.json:

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

Cómo leer los logs

CLI: tail en vivo (recomendado)

Usa el CLI para hacer tail del archivo de log del gateway vía RPC:

openclaw logs --follow

Modos de salida:

  • Sesiones TTY: líneas de log estructuradas, con colores y formato legible.
  • Sesiones no-TTY: texto plano.
  • --json: JSON delimitado por líneas (un evento de log por línea).
  • --plain: forzar texto plano en sesiones TTY.
  • --no-color: desactivar colores ANSI.

En modo JSON, el CLI emite objetos con etiqueta type:

  • meta: metadatos del flujo (archivo, cursor, tamaño)
  • log: entrada de log parseada
  • notice: avisos de truncamiento / rotación
  • raw: línea de log sin parsear

Si el Gateway no es accesible, el CLI muestra un mensaje breve sugiriendo ejecutar:

openclaw doctor

Interfaz de control (web)

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

Logs solo de canales

Para filtrar la actividad de canales (WhatsApp/Telegram/etc), usa:

openclaw channels logs --channel whatsapp

Formatos de log

Logs en archivo (JSONL)

Cada línea del archivo de log es un objeto JSON. El CLI y la interfaz de control parsean estas entradas para renderizar una salida estructurada (hora, nivel, subsistema, mensaje).

Salida de consola

Los logs de consola son sensibles al TTY y están formateados para facilitar la lectura:

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

El formato de consola se controla con logging.consoleStyle.

Configurar el logging

Toda la configuración de logging está bajo 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 de los logs en archivo (JSONL).
  • logging.consoleLevel: nivel de verbosidad de la consola.

Puedes sobreescribir 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 aumentar la verbosidad para una ejecución puntual sin editar openclaw.json. También puedes pasar la opción global del CLI --log-level <level> (por ejemplo, openclaw --log-level debug gateway run), que sobreescribe la variable de entorno para ese comando.

--verbose solo afecta a la salida de consola; no cambia los niveles de log en archivo.

Estilos de consola

logging.consoleStyle:

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

Redacción

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

  • logging.redactSensitive: off | tools (por defecto: tools)
  • logging.redactPatterns: lista de cadenas regex para sobreescribir el conjunto por defecto

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

Diagnósticos + OpenTelemetry

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

Los eventos de diagnóstico se emiten en proceso, pero los exportadores solo se conectan cuando los diagnósticos + el plugin exportador están habilitados.

OpenTelemetry vs OTLP

  • OpenTelemetry (OTel): el modelo de datos + SDKs para trazas, métricas y logs.
  • OTLP: el protocolo de transmisión que se usa para exportar datos de OTel a un collector/backend.
  • OpenClaw exporta vía OTLP/HTTP (protobuf) actualmente.

Señales exportadas

  • Métricas: contadores + histogramas (uso de tokens, flujo de mensajes, encolamiento).
  • Trazas: spans para uso de modelos + procesamiento de webhooks/mensajes.
  • Logs: exportados por OTLP cuando diagnostics.otel.logs está habilitado. El volumen de logs puede ser alto; ten en cuenta logging.level y los filtros del exportador.

Catálogo de eventos de diagnóstico

Uso de modelos:

  • model.usage: tokens, coste, duración, contexto, proveedor/modelo/canal, IDs de sesión.

Flujo de mensajes:

  • webhook.received: ingreso de webhook por canal.
  • webhook.processed: webhook procesado + duración.
  • webhook.error: errores del handler de webhook.
  • message.queued: mensaje encolado para procesamiento.
  • message.processed: resultado + duración + error opcional.

Cola + sesión:

  • queue.lane.enqueue: encolamiento de lane de cola de comandos + profundidad.
  • queue.lane.dequeue: desencolamiento de lane de cola de comandos + tiempo de espera.
  • session.state: transición de estado de sesión + razón.
  • session.stuck: aviso de sesión atascada + antigüedad.
  • run.attempt: metadata de reintentos/intentos de ejecución.
  • diagnostic.heartbeat: contadores agregados (webhooks/cola/sesión).

Habilitar diagnósticos (sin exportador)

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

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

Flags de diagnóstico (logs dirigidos)

Usa flags para activar logs de depuración específicos y dirigidos sin aumentar logging.level. Los flags no distinguen mayúsculas y admiten comodines (ej., telegram.* o *).

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

Sobreescritura por variable de entorno (puntual):

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Notas:

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

Exportar a OpenTelemetry

Los diagnósticos pueden exportarse vía el plugin diagnostics-otel (OTLP/HTTP). Esto funciona con cualquier collector/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 habilitar el plugin con openclaw plugins enable diagnostics-otel.
  • protocol actualmente solo soporta http/protobuf. grpc se ignora.
  • Las métricas incluyen uso de tokens, coste, tamaño del contexto, duración de ejecución y contadores/histogramas de flujo de mensajes (webhooks, encolamiento, estado de sesión, profundidad/espera de cola).
  • Las trazas/métricas se pueden activar con traces / metrics (por defecto: activado). Las trazas incluyen spans de uso de modelos más spans de procesamiento de webhooks/mensajes cuando están habilitadas.
  • Configura headers cuando tu collector requiera autenticación.
  • Variables de entorno soportadas: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL.

Métricas exportadas (nombres + tipos)

Uso de modelos:

  • 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 + 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 + 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 + flush

  • 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 de 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 logs.
  • diagnostics.otel.logs habilita la exportación de logs por 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 logging.level (nivel de log en archivo). La redacción de consola no aplica a los logs OTLP.
  • Las instalaciones de alto volumen deberían preferir el muestreo/filtrado del collector OTLP.

Consejos para solución de problemas

  • ¿El Gateway no es accesible? Ejecuta openclaw doctor primero.
  • ¿Logs vacíos? Verifica que el Gateway esté corriendo y escribiendo en la ruta del archivo en logging.file.
  • ¿Necesitas más detalle? Configura logging.level a debug o trace y reintenta.
Siguiente
Overview
arrow_forward