openclaw/docs/diagnostics/flags.md

summary, read_when, title

summary	read_when	title
Diagnostics flags for targeted debug logs	You need targeted debug logs without raising global logging levels You need to capture subsystem-specific logs for support	Diagnostics flags

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

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

Multiple flags:

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

Restart the gateway after changing flags.

Env override (one-off)

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Disable all flags:

OPENCLAW_DIAGNOSTICS=0

Timeline artifacts

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

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

You can also enable it in config:

{
  "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:

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

Filter for Telegram HTTP diagnostics:

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

Or tail while reproducing:

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.
• Flags are safe to leave enabled; they only affect log volume for the specific subsystem.
• Use /logging to change log destinations, levels, and redaction.

Related

• Gateway diagnostics
• Gateway troubleshooting