Manejo de logs y diagnósticos en OpenClaw

Cuando algo falla en tu aplicación, los logs son tu primera parada. No sé cuántas veces he resuelto problemas complicados simplemente siguiendo el archivo de log en tiempo real y detectando un mensaje de error obvio que no había visto antes.

OpenClaw registra información en dos lugares: un archivo JSON (ideal para procesar datos) y la consola (diseñada para humanos). Aquí tienes cómo encontrar y usar ambos.

Requisitos previos

• Tener el Gateway instalado y funcionando.
• Acceso al archivo de configuración de OpenClaw.
• La CLI de OpenClaw configurada en tu terminal.

Inicio rápido

Por defecto, el Gateway escribe un archivo de log rotativo en esta ruta: /tmp/openclaw/openclaw-YYYY-MM-DD.log

Si prefieres usar una ruta distinta, cámbiala en tu configuración:

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

Para ver qué está pasando ahora mismo, te recomiendo usar la CLI:

openclaw logs --follow

Modos de salida:

• TTY: Formato visual, con colores y estructura clara.
• Non-TTY: Texto plano sin formato.
• --json: JSON delimitado por líneas.
• --plain: Fuerza el modo de texto plano.
• --no-color: Desactiva los colores ANSI.

También puedes ver los logs desde la pestaña Logs en la Control UI ejecutando openclaw control.

Configuración de niveles y estilo

Puedes ajustar qué tanta información ves y cómo se muestra:

{
  logging: {
    level: "info",           // Nivel del log en archivo
    consoleLevel: "info",    // Verbosidad en la consola
    consoleStyle: "pretty"   // Opciones: pretty | compact | json
  }
}

Los niveles disponibles son: trace, debug, info, warn, error. Ten en cuenta que el flag --verbose solo afecta a la consola, no a los logs del archivo.

Redacción de datos sensibles

Para proteger información privada en la consola, usa estas opciones:

{
  logging: {
    redactSensitive: "tools",        // off | tools
    redactPatterns: ["sk-.*"]        // Patrones regex personalizados
  }
}

La redacción solo afecta a la consola. Los logs en archivo permanecen sin redacción para facilitar el debugging técnico.

Diagnostics y OpenTelemetry

Si estás en producción, lo mejor es exportar métricas y traces a tu stack de observabilidad.

Activar Diagnostics

{
  diagnostics: {
    enabled: true
  }
}

Exportar mediante OpenTelemetry

Configura el plugin y los endpoints de esta manera:

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

Qué datos se exportan

Metrics:

• openclaw.tokens: Contador de uso de tokens.
• openclaw.cost.usd: Rastreo de costos.
• openclaw.run.duration_ms: Histograma de duración de ejecuciones.
• openclaw.webhook.received: Actividad de Webhooks.

Traces:

• openclaw.model.usage: Spans de completado del modelo.
• openclaw.webhook.processed: Procesamiento de Webhooks.

Debug Flags

Si necesitas logs específicos sin subir el nivel global, usa los flags de diagnóstico:

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

También puedes activarlos mediante variables de entorno: OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Solución de problemas

”Gateway not reachable”

Ejecuta el comando de diagnóstico:

openclaw doctor

Logs vacíos

Revisa lo siguiente:

• ¿Está el Gateway corriendo?
• ¿La ruta en logging.file es la correcta?

Necesitas más detalle

Cambia el nivel a debug o trace:

{
  logging: {
    level: "debug"
  }
}

Detalles del modo JSON

Al usar --json, la CLI genera objetos con etiquetas de tipo:

Type	Description
meta	Metadatos del stream (archivo, cursor, tamaño)
log	Entrada de log procesada
notice	Avisos de rotación o truncado
raw	Línea de log sin procesar

Métricas exportadas (Referencia)

Model Usage

Metric	Type	Attributes
openclaw.tokens	Counter	type, channel, provider, model
openclaw.cost.usd	Counter	channel, provider, model
openclaw.run.duration_ms	Histogram	channel, provider, model
openclaw.context.tokens	Histogram	context, channel, provider, model

Message Flow

Metric	Type	Attributes
openclaw.webhook.received	Counter	channel, webhook
openclaw.webhook.error	Counter	channel, webhook
openclaw.message.queued	Counter	channel, source
openclaw.message.processed	Counter	channel, outcome

Si todavía tienes dudas, nuestro AI Setup Assistant puede ayudarte a interpretar tus logs.

Próximos pasos

• Debugging → — Modo watch y logging de streams raw.
• Testing → — Suites de pruebas y tests en vivo.
• Gateway Configuration → — Referencia completa de configuración.
• Discord de OpenClaw — Únete a la comunidad para recibir ayuda.