Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

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