Debugging Without the Noise using Diagnostics Flags

Ever tried to fix a production bug but found yourself buried under gigabytes of logs? It is frustrating when you need to see exactly what is happening in one specific part of the system, but turning on verbose logging drowns out the very clues you need. I prefer a surgical approach where I can shine a light on one subsystem without making every other component scream.

Diagnostics flags solve this by letting you enable targeted debug logs. They are opt-in, meaning they do nothing until you specifically ask for them.

What You’ll Need

• A running OpenClaw instance.
• Access to your configuration file.
• Permissions to read log files.
• The OpenClaw CLI installed.

Quick Start

You can enable flags using your configuration file or an environment variable for one-off debugging. Flags are case-insensitive strings and support wildcards.

1. Enable via config

Open your config file and add the diagnostics block. You can specify single flags or use wildcards like gateway.*.

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

Restart the gateway after you save these changes.

2. Use an environment override

If you do not want to edit your config file, use the OPENCLAW_DIAGNOSTICS environment variable. This is great for quick tests.

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

To turn everything off, set it to zero:

OPENCLAW_DIAGNOSTICS=0

3. Extract your logs

Logs go to the standard diagnostics log file. By default, you can find them here: /tmp/openclaw/openclaw-YYYY-MM-DD.log. If you have customized logging.file, check that path instead.

To find the latest log file and filter for specific errors, I use these commands:

# Find the latest log
ls -t /tmp/openclaw/openclaw-*.log | head -n 1

# Filter for Telegram HTTP errors
rg "telegram http error" /tmp/openclaw/openclaw-*.log

You can also watch logs in real-time while you reproduce an issue:

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

Troubleshooting

Logs are not appearing

If you enabled flags but see nothing in the logs, check your logging.level. If this is set higher than warn (like error), diagnostics logs are suppressed. The default info level works fine.

Remote log access

If you are running a remote gateway and cannot access the file system directly, use the CLI tool to stream logs:

openclaw logs --follow

Flags are safe to leave enabled because they only increase log volume for the specific subsystems you choose. They do not affect the performance of other parts of the system.

If you have questions about specific flag names, ask the AI Setup Assistant.

What’s Next

• CLI Logs Reference
• Global Logging Configuration