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

FlagEnables
telegram.httpTelegram Bot API HTTP error logging
brave.httpBrave Search request/response/cache logging
profilerReply-stage profiler and Codex app-server profiler (both)
reply.profilerReply-stage profiler only
codex.profilerCodex app-server profiler only
timelineStructured JSONL timeline artifact (see below)

​
Enable via config

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

​
Env override (one-off)

OPENCLAW_DIAGNOSTICS=telegram.http,brave.http
Values split on commas or whitespace. Special values:
ValueEffect
0, false, off, noneDisable all flags, overriding config too
1, true, all, *Enable every flag
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: 
OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run
Enable only reply-dispatch profiler spans: 
OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run
Enable only Codex app-server startup/tool/thread profiler spans: 
OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run
profiler enables both the reply profiler and the Codex profiler; use the scoped flag names to enable just one. Or set it in config: 
{
  "diagnostics": {
    "flags": ["reply.profiler", "codex.profiler"]
  }
}
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: 
OPENCLAW_DIAGNOSTICS=timeline \
OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \
openclaw gateway run
Or enable it in config: 
{
  "diagnostics": {
    "flags": ["timeline"]
  }
}
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: 
/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. See Logging for the full log-path resolution, rotation, and redaction model.

​
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
Filter for Brave Search HTTP diagnostics: 
rg "brave http" /tmp/openclaw/openclaw-*.log
Or tail while reproducing: 
tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"
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.