Diagnostics Flags: Cómo depurar sin inundar tus logs

¿Te ha pasado que activas el modo de depuración y de repente tu terminal se llena de miles de líneas irrelevantes? Intentar encontrar un error específico en medio de tanto ruido es agotador y te quita tiempo valioso que podrías usar para arreglar el problema real.

Los Diagnostics Flags son la mejor solución para esto. Te permiten activar logs de depuración específicos para un subsistema sin tener que activar el modo verbose en toda la aplicación.

Requisitos previos

• Una instancia de Gateway configurada.
• Acceso para editar el archivo de configuración o las variables de entorno.

Inicio rápido

Puedes activar estas banderas de dos formas distintas dependiendo de si buscas algo permanente o una prueba rápida.

1. Configuración permanente

Añade las banderas directamente en tu archivo de configuración. Es la mejor opción si estás desarrollando un módulo específico.

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

Recuerda reiniciar el Gateway después de guardar los cambios para que se apliquen.

2. Sobrescritura por variable de entorno

Si solo necesitas revisar algo rápido sin tocar archivos, usa variables de entorno:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Para desactivar todas las banderas de golpe, usa:

OPENCLAW_DIAGNOSTICS=0

Cómo funcionan las banderas

Las banderas son cadenas de texto que no distinguen entre mayúsculas y minúsculas. Funcionan de forma opcional: si no las activas, no afectan en nada.

Puedes usar wildcards para ser más eficiente:

• telegram.*: Captura todo lo relacionado con el subsistema de Telegram (como telegram.http).
• *: Activa absolutamente todas las banderas disponibles.

Dónde encontrar los logs

Por defecto, los logs se guardan en formato JSONL (un objeto JSON por línea) en esta ruta:

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

Si has definido una ruta distinta en logging.file, revisa ese archivo. Ten en cuenta que la censura de datos sensibles configurada en logging.redactSensitive se sigue aplicando aquí.

Extraer información útil

Para encontrar el archivo de log más reciente:

ls -t /tmp/openclaw/openclaw-*.log | head -n 1

Si quieres filtrar errores específicos de Telegram:

rg "telegram http error" /tmp/openclaw/openclaw-*.log

Para ver los logs en tiempo real mientras reproduces un error:

tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"

Si tu Gateway es remoto, usa el comando openclaw logs --follow.

Solución de problemas

No aparecen los logs de diagnóstico aunque activé las banderas Revisa tu logging.level. Si está configurado en un nivel superior a warn (como error), es posible que estos logs se estén suprimiendo. El nivel info predeterminado funciona correctamente.

Las banderas afectan al rendimiento Es seguro dejar las banderas activadas. Solo afectan al volumen de logs del subsistema específico que hayas elegido y no impactan globalmente.

---

¿Necesitas ayuda para configurar una bandera específica? Prueba el AI Setup Assistant.

Próximos pasos

• /logging: Cambia destinos y niveles de log.
• /cli/logs: Domina el manejo de logs desde la CLI.