Gateway Health and Doctor Commands in OpenClaw: Check Status First, Repair Second

Most OpenClaw outages are made worse by the same instinct: touch config first, think later.

A better model is hospital triage. You do not start with surgery because a patient looks unwell. You check vital signs, confirm where the problem is, and only then decide whether the fix is observation, intervention, or repair.

That is the job split between openclaw status, openclaw health, and openclaw doctor. One gives you the fast overview, one asks the running gateway for a health snapshot, and one handles findings, migrations, and supported repair steps.

If you keep those surfaces separate, troubleshooting gets calmer fast. If you blur them together, every problem starts to look like a reason to poke the machine with a wrench.

What to check first when something feels broken

Start with the fastest read-only view that can still narrow the problem.

Run openclaw status: quick summary of gateway reachability, mode, channel auth age, sessions, and recent activity
Escalate to openclaw status --deep: adds live probes when the quick view looks suspicious but not conclusive
Use openclaw health or openclaw health --verbose: ask the running gateway for its health snapshot, with verbose forcing a live probe
Use openclaw doctor --lint: read-only findings for config drift, stale state, or known health issues
Use openclaw doctor --fix only when you want changes: this is the supported repair lane, not the first reflex

That order matters because the first question is not, "How do I repair this?" It is, "What exactly is unhealthy?"

Status is the dashboard, not the mechanic

openclaw status is the fast operator view. It is meant to answer the boring questions that save you the most time.

Is the gateway reachable?
Is this local or remote mode?
Are channels linked and how old is that auth state?
Is there recent session activity?
Are there obvious warnings about memory, secrets, pricing, or updates?

The plain command stays on the quick read-only path. That is why it is the right first move when the agent suddenly goes quiet. It tells you whether you are dealing with a broad health problem or just a narrow failure lane.

openclaw status --deep is the escalation step. It asks for live probes and gives you a stronger answer when the dashboard feels inconclusive.

# fast first pass
openclaw status

# stronger read-only diagnosis with live probes
openclaw status --deep

# include broader local detail when you need a fuller pasteable report
openclaw status --all

Health is the gateway snapshot lane

openclaw health is different from status. It asks the running gateway for its health snapshot over gateway RPC.

That sounds subtle, but it matters. The CLI is not opening direct provider sockets itself. It is asking the gateway what the gateway sees. So health is great for understanding the live gateway view, but it is not a magic side channel that bypasses gateway reality.

By default, health can return a fresh cached snapshot and let the gateway refresh in the background. openclaw health --verbose forces a live probe and prints more connection detail. That makes it useful when you need a stronger current-state answer without jumping straight into repair mode.

# gateway health snapshot
openclaw health

# machine-readable output
openclaw health --json

# force a live probe and print more detail
openclaw health --verbose

Doctor is the repair and migration tool

Doctor is where many users get confused. They treat it like a prettier version of status. It is not.

openclaw doctor is the health-check and repair surface for gateway config, channels, plugins, skills, model auth, local state, and migrations. Think of it as the mechanic with a checklist and a toolbox, not the dashboard on the steering wheel.

The important split is this:

openclaw doctor: human-oriented inspection and guided prompts
openclaw doctor --lint: read-only structured findings for CI, preflight, and disciplined troubleshooting
openclaw doctor --fix: apply supported repairs when you are ready for changes
openclaw doctor --non-interactive: conservative no-prompt path that skips repairs needing human confirmation

This is the moment where a lot of people get burned. --non-interactive is not the same thing as --fix. One is cautious automation. The other is an intentional repair lane.

# read-only findings first
openclaw doctor --lint

# narrow one check if you already know the likely lane
openclaw doctor --lint --only core/doctor/gateway-config --json

# apply supported repairs when you want doctor to make changes
openclaw doctor --fix

# conservative automation mode, not equivalent to repair
openclaw doctor --non-interactive

How to tell config, runtime, and channel problems apart

A useful first troubleshooting pass should separate symptoms by layer.

Status looks bad immediately: likely gateway reachability, auth age, obvious state, or a top-level warning
Health probe looks weak: likely running-gateway connectivity or channel health inside the gateway
Doctor lint finds issues: likely config drift, stale state, migrations, permissions, or other known repairable conditions
All three look healthy but one workflow still fails: likely a narrower runtime, tool, or code-path problem

That last case is where people panic and reinstall things that were not broken. Resist the urge. A healthy gateway with one failing workflow usually needs targeted debugging, not ritual sacrifice.

Where diagnostics flags fit

Once status, health, or doctor tells you which lane smells wrong, diagnostics flags help you go from broad signal to specific evidence.

They are best when you already suspect a subsystem and want targeted logs without globally turning everything into noise. Flags are opt-in, case-insensitive, and support wildcards like gateway.*.

# targeted gateway diagnostics for one run
OPENCLAW_DIAGNOSTICS=gateway.* openclaw gateway run

# reply-path timing only
OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

# disable all diagnostics flags for this process
OPENCLAW_DIAGNOSTICS=0 openclaw gateway run

If you want the fuller diagnostics story, go deeper with Diagnostics & Debug Flags. This page is about choosing the right surface first, not drowning in logs on minute one.

A sane troubleshooting flow

If you want one repeatable operator habit, use this:

run openclaw status
escalate to openclaw status --deep if the summary is not enough
use openclaw health --verbose when you need a fresh live gateway probe
run openclaw doctor --lint before any repair action
use openclaw doctor --fix only for supported changes you actually want
turn on targeted diagnostics only after you know which subsystem deserves the attention

The sequence is not glamorous. Good. Most reliable operations are not.

The short version

status is the fast summary
status --deep is the stronger read-only escalation
health asks the running gateway for its health snapshot
health --verbose forces a live probe
doctor --lint is the safe read-only findings lane
doctor --fix is the supported repair lane

Check status first. Confirm health second. Repair third. That order alone will save you from a surprising amount of self-inflicted trouble.

Need help from people who already use this stuff?

Trying to debug OpenClaw without making a small issue bigger?

Bring your status output, health probe result, and doctor findings into the community. Clean evidence beats random repair energy every time.

Join My AI Agent Profit Lab See the community page

FAQ

What should I run first when OpenClaw stops replying?

Start with openclaw status. It is the fast read-only summary for gateway reachability, channel auth age, recent activity, and obvious warning signs. Escalate to status --deep or openclaw health --verbose only when the quick view is not enough.

What is the difference between status and health?

Status is the quick operator dashboard. Health asks the running gateway for a health snapshot. status --deep is the broader escalation view, while health --verbose forces a live probe and exposes more gateway connection detail.

When should I use doctor instead of status or health?

Use doctor when you need findings and repair guidance, not just visibility. status and health help you see what is wrong. doctor helps you validate config, stale state, migrations, and supported repair paths.

What does doctor --fix change that doctor --lint does not?

doctor --lint is read-only and returns structured findings. doctor --fix, which is the repair alias, can apply supported repairs. That makes lint safer for preflight checks and fix the right choice only when you are ready for changes.

When are diagnostics flags better than verbose logging everywhere?

When you already know the suspicious subsystem. Diagnostics flags give you targeted signal, such as gateway, Telegram, or profiler spans, without turning the whole log stream into noise.

Gateway Health and Doctor Commands