Logging

Para un resumen orientado al usuario (CLI + Control UI + configuración), consulta /logging.

OpenClaw tiene dos “superficies” de log:

• Salida de consola (lo que ves en la terminal / Debug UI).
• Logs de archivo (líneas JSON) escritos por el logger del gateway.

Logger basado en archivo

• El archivo de log rotativo por defecto está bajo /tmp/openclaw/ (un archivo por día): openclaw-YYYY-MM-DD.log
  • La fecha usa la zona horaria local del host del gateway.
• La ruta del archivo de log y el nivel se pueden configurar vía ~/.openclaw/openclaw.json:
  • logging.file
  • logging.level

El formato del archivo es un objeto JSON por línea.

La pestaña Logs del Control UI hace tail de este archivo vía el gateway (logs.tail). El CLI puede hacer lo mismo:

openclaw logs --follow

Verbose vs. niveles de log

• Los logs de archivo se controlan exclusivamente por logging.level.
• --verbose solo afecta la verbosidad de la consola (y el estilo de log WS); no eleva el nivel de log del archivo.
• Para capturar detalles solo de verbose en logs de archivo, configura logging.level a debug o trace.

Captura de consola

El CLI captura console.log/info/warn/error/debug/trace y los escribe en los logs de archivo, mientras sigue imprimiendo en stdout/stderr.

Puedes ajustar la verbosidad de la consola independientemente vía:

• logging.consoleLevel (por defecto info)
• logging.consoleStyle (pretty | compact | json)

Redacción de resúmenes de herramientas

Los resúmenes verbose de herramientas (ej. 🛠️ Exec: ...) pueden enmascarar tokens sensibles antes de que lleguen al flujo de la consola. Esto es solo para herramientas y no altera los logs de archivo.

• logging.redactSensitive: off | tools (por defecto: tools)
• logging.redactPatterns: array de cadenas regex (sobrescribe los valores por defecto)
  • Usa cadenas regex sin procesar (gi automático), o /patron/flags si necesitas flags personalizadas.
  • Las coincidencias se enmascaran manteniendo los primeros 6 + últimos 4 caracteres (longitud >= 18), sino ***.
  • Los valores por defecto cubren asignaciones de claves comunes, flags CLI, campos JSON, cabeceras bearer, bloques PEM y prefijos de tokens populares.

Logs WebSocket del Gateway

El gateway imprime logs del protocolo WebSocket en dos modos:

• Modo normal (sin --verbose): solo se imprimen resultados RPC “interesantes”:
  • errores (ok=false)
  • llamadas lentas (umbral por defecto: >= 50ms)
  • errores de parseo
• Modo verbose (--verbose): imprime todo el tráfico de solicitud/respuesta WS.

Estilo de log WS

openclaw gateway soporta un selector de estilo por gateway:

• --ws-log auto (por defecto): el modo normal está optimizado; el modo verbose usa salida compacta
• --ws-log compact: salida compacta (solicitud/respuesta emparejadas) cuando está en verbose
• --ws-log full: salida completa por frame cuando está en verbose
• --compact: alias de --ws-log compact

Ejemplos:

# optimizado (solo errores/lentos)
openclaw gateway

# mostrar todo el tráfico WS (emparejado)
openclaw gateway --verbose --ws-log compact

# mostrar todo el tráfico WS (meta completa)
openclaw gateway --verbose --ws-log full

Formato de consola (logging de subsistemas)

El formateador de consola es consciente del TTY e imprime líneas consistentes con prefijo. Los loggers de subsistema mantienen la salida agrupada y escaneable.

Comportamiento:

• Prefijos de subsistema en cada línea (ej. [gateway], [canvas], [tailscale])
• Colores de subsistema (estables por subsistema) más coloración por nivel
• Color cuando la salida es un TTY o el entorno parece un terminal rico (TERM/COLORTERM/TERM_PROGRAM), respeta NO_COLOR
• Prefijos de subsistema acortados: elimina el gateway/ + channels/ inicial, mantiene los últimos 2 segmentos (ej. whatsapp/outbound)
• Sub-loggers por subsistema (prefijo automático + campo estructurado { subsystem })
• logRaw() para salida QR/UX (sin prefijo, sin formato)
• Estilos de consola (ej. pretty | compact | json)
• Nivel de log de consola separado del nivel de log de archivo (el archivo mantiene el detalle completo cuando logging.level está configurado en debug/trace)
• Los cuerpos de mensajes de WhatsApp se registran a nivel debug (usa --verbose para verlos)

Esto mantiene los logs de archivo existentes estables mientras hace la salida interactiva escaneable.