ContextQMD
Back to Openclaw

Diagnostics flags

docs/diagnostics/flags.md

2026.5.53.3 KB
Original Source

Diagnostics flags let you enable targeted debug logs without turning on verbose logging everywhere. Flags are opt-in and have no effect unless a subsystem checks them.

How it works

  • Flags are strings (case-insensitive).
  • You can enable flags in config or via an env override.
  • Wildcards are supported:
    • telegram.* matches telegram.http
    • * enables all flags

Enable via config

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

Multiple flags:

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

Restart the gateway after changing flags.

Env override (one-off)

bash
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Disable all flags:

bash
OPENCLAW_DIAGNOSTICS=0

Timeline artifacts

The timeline flag writes structured startup and runtime timing events for external QA harnesses:

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

You can also enable it in config:

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

The timeline file path still comes from OPENCLAW_DIAGNOSTICS_TIMELINE_PATH. When timeline is enabled only from config, the earliest config-loading spans are not emitted because OpenClaw has not read config yet; subsequent startup spans use the config flag.

OPENCLAW_DIAGNOSTICS=1, OPENCLAW_DIAGNOSTICS=all, and OPENCLAW_DIAGNOSTICS=* also enable the timeline because they enable every diagnostics flag. Prefer timeline when you only want the JSONL timing artifact.

Timeline records use the openclaw.diagnostics.v1 envelope. Events can include process ids, phase names, span names, durations, plugin ids, dependency counts, event-loop delay samples, provider operation names, child-process exit state, and startup error names/messages. Treat timeline files as local diagnostics artifacts; review them before sharing outside your machine.

Where logs go

Flags emit logs into the standard diagnostics log file. By default:

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

If you set logging.file, use that path instead. Logs are JSONL (one JSON object per line). Redaction still applies based on logging.redactSensitive.

Extract logs

Pick the latest log file:

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

Filter for Telegram HTTP diagnostics:

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

Filter for Brave Search HTTP diagnostics:

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

Or tail while reproducing:

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

For remote gateways, you can also use openclaw logs --follow (see /cli/logs).

Notes

  • If logging.level is set higher than warn, these logs may be suppressed. Default info is fine.
  • brave.http logs Brave Search request URLs/query params, response status/timing, and cache hit/miss/write events. It does not log API keys or response bodies, but search queries can be sensitive.
  • Flags are safe to leave enabled; they only affect log volume for the specific subsystem.
  • Use /logging to change log destinations, levels, and redaction.