Diagnostics & Debug Flags

Most OpenClaw debugging goes sideways for one simple reason: people change three things before they understand the first thing.

A better mental model is a car dashboard. If one warning light comes on, you do not tear out the radio, replace the battery, and kick the tire for emotional balance. You check which system is complaining, how serious it is, and what evidence you can gather before making the next move.

The official diagnostics flags guide and doctor command reference are the two best starting points here. Together they explain how to get targeted evidence instead of turning your whole gateway into a fog machine.

This page is about evidence gathering once you are already debugging. If your first question is simply what to check first when OpenClaw feels broken, keep that operator triage angle separate from the heavier diagnostics surface. That boundary matters because first-pass health checks and subsystem tracing are related, but they are not the same job.

Start with the first debugging steps, not the dramatic ones

When OpenClaw acts strange, the smartest opening move is usually boring. Good. Boring is how you get out of guessing.

1. Reproduce the symptom cleanly: know what failed, where, and whether it happens again
2. Run doctor in inspection mode: use structured health checks before making edits
3. Read the current logs: see whether the issue is startup, auth, channel transport, plugin load, or runtime behavior
4. Enable only the diagnostics you need: add targeted flags for the subsystem that looks guilty
5. Change one thing at a time: otherwise your evidence becomes soup

That order matters. Diagnostics flags are powerful, but they are not step one for every problem. Sometimes doctor already tells you the config is wrong. Sometimes the logs already show the connection dropped. No need to put on a lab coat when the cable is unplugged.

What diagnostics flags actually do

Diagnostics flags let you light up a narrow part of the system without globally cranking log volume. OpenClaw treats them as targeted opt-in debug lanes.

That means you can inspect one failing area, such as Telegram HTTP behavior, gateway timing, or profiler spans, without drowning every other subsystem in noise. The official docs also note that flags are case-insensitive and support wildcards, so gateway.* or even * can widen the scope when you truly need it.

In practice, focused beats broad most of the time. A narrow log stream is easier to read, faster to share with support, and less likely to expose unrelated sensitive details.

# one-off targeted diagnostics
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway run

# profiling for one run
OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

# disable every diagnostics flag for this process
OPENCLAW_DIAGNOSTICS=0 openclaw gateway run

Know where the logs live before you panic

OpenClaw diagnostics output goes into the normal diagnostics log file by default, typically under /tmp/openclaw/openclaw-YYYY-MM-DD.log. If your setup defines logging.file, use that location instead.

This is why openclaw logs matters so much. It gives you a clean way to inspect gateway file logs, including remote mode, without treating SSH as your only debugging religion. It also supports follow mode, JSON output, and local versus UTC timestamp rendering.

The useful habit is simple: reproduce the issue, tail the relevant logs, then add targeted flags if the existing lines are not specific enough. People often do that in reverse, which is how one small mystery becomes a 500-line confession booth.

Doctor is for health and guided findings, not just emergencies

A lot of operators treat openclaw doctor like a last-resort ambulance. The docs suggest a better posture. Doctor is the general health surface for gateway, channels, plugins, skills, model routing, local state, and config migrations.

It helps to think in three modes:

• inspect: human-oriented checks and guided prompts
• repair: supported fixes when you intentionally want doctor to make changes
• lint: read-only structured findings for CI, preflight, or disciplined debugging

For weird behavior, openclaw doctor --lint is often the best first move because it stays read-only and forces the conversation back toward evidence.

# read-only health checks
openclaw doctor --lint

# filter the logs while reproducing
openclaw logs --follow

# focus doctor on one check when needed
openclaw doctor --lint --only core/doctor/gateway-config --json

Common runtime breakpoints to check first

Not every OpenClaw failure lives in the same layer. That is why random retries feel so unconvincing.

These are the breakpoints worth separating early:

• gateway startup: config problems, service state, token issues, or plugin load failures
• channel layer: auth, permissions, transport, or formatting problems on Telegram, Discord, and similar surfaces
• tool/runtime layer: exec policy, sandbox boundaries, node pairing, browser state, or provider auth
• content/runtime bugs: a specific command path or dev script crashes, even when the gateway itself is broadly healthy

The OpenClaw docs even include narrow debug notes for cases like the Node plus tsx crash path. That is a good reminder that some bugs are not "the system is broken" bugs. They are "this one runtime path has a known sharp edge" bugs. Different problem, different fix.

When to widen scope and when to stop guessing

Sometimes the first pass is enough. Other times you need to widen the lens. The trick is doing that on purpose.

• Widen diagnostics when a narrow flag shows symptoms but not cause
• Use profiler flags when timing or startup sequencing is the real mystery
• Switch to doctor findings when config or state integrity may be involved
• Escalate to a minimal repro when the issue looks like a code path bug, not an operator mistake

A good debugging rule is this: if your next change is based on annoyance rather than evidence, stop. That is the moment to collect one better log line, one cleaner repro, or one narrower hypothesis.

A practical workflow that stays sane

If you want a repeatable operator habit, use this sequence:

1. capture the exact symptom and time
2. run openclaw doctor --lint
3. review recent lines with openclaw logs
4. enable the smallest useful diagnostics flag set
5. reproduce once
6. decide whether this is config, transport, runtime, or code-path specific

Notice what is missing from that list: panic editing, random reinstalls, and six speculative config changes. Very brave. Rarely useful.

The short version

Diagnostics flags are for targeted evidence, not dramatic theater. Logs tell you what happened. Doctor tells you what health checks already know. Together they help you separate a bad config, a flaky integration, and a real runtime bug without lighting the whole system on fire.

The fastest way to debug OpenClaw is usually not more guessing. It is less guessing, done in a better order.