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", "brave.http", "gateway.*"]
  }
}

Restart the gateway after changing flags.

Env override (one-off)

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Disable all flags:

OPENCLAW_DIAGNOSTICS=0

OPENCLAW_DIAGNOSTICS=0 is a process-level disable override: it disables flags from both env and config for that process.

Profiling flags

Profiler flags enable targeted timing spans without raising global logging levels. They are disabled by default.

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

Enable profiler flags from 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. To temporarily disable every diagnostics flag even when config enables profiler flags, start the process with:

OPENCLAW_DIAGNOSTICS=0 openclaw gateway run

Timeline artifacts

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

OPENCLAW_DIAGNOSTICS=timeline openclaw gateway run

You can also enable it in config:

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

Timeline events are stored in the shared SQLite state database under the diagnostics.timeline scope. 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 timing diagnostics.

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. Export/debug commands can materialize a file artifact from the database when you need to attach diagnostics.

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

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, 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.

Related

• Gateway diagnostics
• Gateway troubleshooting