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:
  • text

    Copy

    telegram.*
    matches
    text

    Copy

    telegram.http
  • text

    Copy

    *
    enables all flags

Enable via config

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

Multiple flags:

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

Restart the gateway after changing flags.

Env override (one-off)

bash
Copy
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Disable all flags:

bash
Copy
OPENCLAW_DIAGNOSTICS=0

Timeline artifacts

The

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

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

You can also enable it in config:

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

The timeline file path still comes from

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

, , and also enable the timeline because they enable every diagnostics flag. Prefer when you only want the JSONL timing artifact.

Timeline records use the

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:

text
Copy
/tmp/openclaw/openclaw-YYYY-MM-DD.log

If you set

, use that path instead. Logs are JSONL (one JSON object per line). Redaction still applies based on .

Extract logs

Pick the latest log file:

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

Filter for Telegram HTTP diagnostics:

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

Or tail while reproducing:

bash
Copy
tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"

For remote gateways, you can also use

(see /cli/logs).

Notes

• If
  text

  Copy

  logging.level
  is set higher than
  text

  Copy

  warn
  , these logs may be suppressed. Default
  text

  Copy

  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