Diagnosevlaggen

Met diagnostische vlaggen kun je gerichte debuglogs inschakelen zonder overal uitgebreide logging aan te zetten. Vlaggen zijn opt-in en hebben geen effect tenzij een subsysteem ze controleert.

# Hoe het werkt

• Vlaggen zijn tekenreeksen (niet hoofdlettergevoelig).
• Je kunt vlaggen inschakelen in de configuratie of via een env-override.
• Wildcards worden ondersteund:
  • telegram.* komt overeen met telegram.http
  • * schakelt alle vlaggen in

# Inschakelen via configuratie

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

Meerdere vlaggen:

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

Herstart de Gateway nadat je vlaggen hebt gewijzigd.

# Env-override (eenmalig)

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Alle vlaggen uitschakelen:

OPENCLAW_DIAGNOSTICS=0

# Timeline-artefacten

De vlag timeline schrijft gestructureerde timinggebeurtenissen bij opstarten en tijdens runtime voor externe QA-harnassen:

OPENCLAW_DIAGNOSTICS=timeline \
OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \
openclaw gateway run

Je kunt deze ook inschakelen in de configuratie:

{
  "diagnostics": {
    "flags": ["timeline"]
  }
}

Het pad naar het timeline-bestand komt nog steeds uit OPENCLAW_DIAGNOSTICS_TIMELINE_PATH. Wanneer timeline alleen via configuratie is ingeschakeld, worden de vroegste spans voor het laden van de configuratie niet uitgezonden, omdat OpenClaw de configuratie nog niet heeft gelezen; daaropvolgende opstartspans gebruiken de configuratievlag.

OPENCLAW_DIAGNOSTICS=1, OPENCLAW_DIAGNOSTICS=all en OPENCLAW_DIAGNOSTICS=* schakelen ook de timeline in, omdat ze elke diagnostische vlag inschakelen. Geef de voorkeur aan timeline wanneer je alleen het JSONL-timingartefact wilt.

Timeline-records gebruiken de envelop openclaw.diagnostics.v1. Gebeurtenissen kunnen proces-id's, fasenamen, spannamen, duurwaarden, Plugin-id's, aantallen afhankelijkheden, event-loop-vertragingssamples, namen van providerbewerkingen, exitstatus van child-processen en namen/berichten van opstartfouten bevatten. Behandel timeline-bestanden als lokale diagnostische artefacten; controleer ze voordat je ze buiten je machine deelt.

# Waar logs naartoe gaan

Vlaggen schrijven logs naar het standaard diagnostische logbestand. Standaard:

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

Als je logging.file instelt, gebruik dan in plaats daarvan dat pad. Logs zijn JSONL (één JSON-object per regel). Redactie blijft van toepassing op basis van logging.redactSensitive.

# Logs extraheren

Kies het nieuwste logbestand:

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

Filter op Telegram HTTP-diagnostiek:

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

Filter op Brave Search HTTP-diagnostiek:

rg "brave http" /tmp/openclaw/openclaw-*.log

Of volg de logs tijdens het reproduceren:

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

Voor externe Gateways kun je ook openclaw logs --follow gebruiken (zie /cli/logs).

# Opmerkingen

• Als logging.level hoger is ingesteld dan warn, kunnen deze logs worden onderdrukt. De standaardwaarde info is prima.
• brave.http logt Brave Search-aanvraag-URL's/queryparameters, responsstatus/timing en gebeurtenissen voor cache-hit/miss/write. Het logt geen API-sleutels of responsbodies, maar zoekopdrachten kunnen gevoelig zijn.
• Vlaggen kunnen veilig ingeschakeld blijven; ze beïnvloeden alleen het logvolume voor het specifieke subsysteem.
• Gebruik /logging om logbestemmingen, niveaus en redactie te wijzigen.

# Gerelateerd

• Gateway-diagnostiek
• Gateway-probleemoplossing