Skip to main content
Diagnostics flags turn on extra logging for one subsystem without raising logging.level globally. A flag has no effect unless a subsystem checks it.

​
How it works

  • Flags are case-insensitive strings, resolved from diagnostics.flags in config plus the OPENCLAW_DIAGNOSTICS env override, deduped and lowercased.
  • name.* matches name itself and anything under name. (for example telegram.* matches telegram.http).
  • * or all enables every flag.
  • Restart the gateway after changing diagnostics.flags in config; it is not hot-reloaded.

​
Known flags

​
Enable via config

Multiple flags:

​
Env override (one-off)

Values split on commas or whitespace. Special values: OPENCLAW_DIAGNOSTICS=0 disables flags from both env and config for that process, useful for temporarily silencing a profiler flag left on in config without editing the file.

​
Profiler flags

Profiler flags gate lightweight timing spans; they add no overhead when off. Enable all profiler-gated spans for one gateway run:
Enable only reply-dispatch profiler spans:
Enable only Codex app-server startup/tool/thread profiler spans:
profiler enables both the reply profiler and the Codex profiler; use the scoped flag names to enable just one. Or set it in config:
Restart the gateway after changing config flags. To disable a profiler flag, remove it from diagnostics.flags and restart, or start the process with OPENCLAW_DIAGNOSTICS=0 to override every diagnostics flag for that run.

​
Timeline artifacts

The timeline flag (alias: diagnostics.timeline) writes structured startup and runtime timing events as JSONL, for external QA harnesses:
Or enable it in config:
The output path always comes from OPENCLAW_DIAGNOSTICS_TIMELINE_PATH, even when the flag itself is set in config; there is no config key for the path. When timeline is enabled only from config, the earliest config-loading spans are missing because OpenClaw has not read config yet; subsequent startup spans are captured normally. OPENCLAW_DIAGNOSTICS=1, =all, and =* also enable the timeline, since they enable every flag. Prefer the scoped timeline flag when you only want the JSONL artifact and not every other diagnostics flag. Event-loop delay samples in the timeline need one more opt-in beyond timeline: set OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 (or on/true/yes) on top of enabling the timeline. Timeline records use the openclaw.diagnostics.v1 envelope and 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 before sharing them outside your machine.

​
Where logs go

Flags emit logs into the standard diagnostics log file. By default:
If you set logging.file, use that path instead. Logs are JSONL (one JSON object per line). Redaction still applies based on logging.redactSensitive. See Logging for the full log-path resolution, rotation, and redaction model.

​
Extract logs

Pick the latest log file:
Filter for Telegram HTTP diagnostics:
Filter for Brave Search HTTP diagnostics:
Or tail while reproducing:
For remote gateways, use openclaw logs --follow instead (see /cli/logs).

​
Notes

  • If logging.level is set higher than warn, flag-gated 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 the API key (sent as a request header) 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.