OpenClaw status vs health: --all, --deep, --usage, the 60-Second Cache, and Which Check Belongs in Cron

A green health check can be up to a minute old.

Search openclaw status and you get the official CLI reference, a mirror of the same docs on another domain at roughly 400 words, and a hosting company's command cheatsheet that gives status one line ("Check system / agent status") and moves on. All three list --all, --deep, and --usage. None of them puts status, health, and the Gateway's HTTP endpoints side by side and says which one belongs in a cron job, which one belongs in an uptime monitor, and which one you paste into a bug report. That is the whole point of this page. They are five different questions wearing similar names.

Plain status is the fast, read-only one

openclaw status
openclaw status --json

With no flags, openclaw status gives you a local summary: whether the Gateway is reachable, how old each linked channel's authentication is, recent activity, per-agent session stores when you run more than one agent, and the install and runtime state of the Gateway and node host services. It also carries update information, including the update channel, the git SHA on source installs, and a hint to run openclaw update when something newer exists.

It stays on the fast path on purpose. Memory is a good example. Plain status skips memory inspection and marks it not checked, which is different from unavailable. Not checked means nobody looked.

Session lines separate Execution: from Runtime:. Execution is the sandbox path (direct, or a docker/* target). Runtime is what is actually driving the session: OpenClaw Default, OpenAI Codex, a CLI backend, or an ACP backend. If a session is behaving like a different agent than you expected, this is the line to read first, and the sandbox guide explains the Execution half.

--all is the one you paste into an issue

openclaw status --all

The docs describe --all as a full diagnosis that is read-only and pasteable. It adds a security audit, plugin compatibility, and memory-vector checks on top of the plain report, and with --json it reports memory details from the active memory plugin runtime. When a maintainer asks for "your status output," this is what they mean. I still skim it before pasting, out of habit, because hostnames and account names are nobody else's business.

--deep actually talks to your channels

--deep asks the running Gateway for live channel health, with per-account probes against WhatsApp Web, Telegram, Discord, Google Chat, Slack, and Signal, and it turns on the security audit too. This is slower and it touches real services. Run it when a channel looks fine on paper and messages still are not arriving. The channels CLI guide covers channels status --probe, which is the narrower version of the same idea.

How results read: channels without an explicit check report lifecycle health instead. Healthy shows as OK. Degraded and failed both show as WARN, so a WARN on its own won't say how bad things are.

--usage answers the quota question

openclaw status --usage
openclaw status --usage --agent work

This prints normalized provider usage windows as X% left. On a multi-agent install, --agent <id> picks whose auth scope gets checked, which matters when two agents sign in to the same provider with different accounts. For the model side of the picture (which routes exist, which ones are failing) the models CLI guide is the better tool.

One deadline, shared

Status runs on a single monotonic deadline, 60,000 ms by default, set with --timeout <ms>. Local readiness, the Gateway check, and provider usage all draw from the same budget, so a slow provider usage call eats time the Gateway check would have had. If the Gateway is still starting when the budget runs out, status says still starting instead of unreachable and skips the deep channel checks. When a run feels slow and you cannot tell why:

OPENCLAW_DIAGNOSTICS=timeline \
OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-status-timeline.jsonl \
  openclaw status --json

--verbose (or --debug) prints which Gateway target status resolved before the report, the fastest way to catch a CLI pointed at the wrong machine.

A small kindness in the update section: after a failed update, status keeps the outcome. It relabels that failure as historical once the local Gateway passes current readiness and connection checks and its serving version matches the recorded update target. So an old red line next to a working Gateway is not necessarily current news. The upgrade guide has the rest of that story.

openclaw health is the Gateway's own opinion

openclaw health
openclaw health --json
openclaw health --timeout 2500
openclaw health --verbose

health asks a running Gateway for a snapshot over WebSocket RPC. The CLI never opens the channel sockets itself. That makes it cheap, and it also means that without --verbose, the Gateway may hand back a cached snapshot up to 60 seconds old while it refreshes in the background. Hence the first line of this page.

--verbose (same as --debug) forces live checks and expands output across every account and agent. Unhealthy channels come back with their recorded startup errors attached. A disabled account shows disabled without hiding results from your other accounts. Plugin diagnostics appear for enabled or configured plugins; JSON keeps full values while text output is sanitized for the terminal.

The part I use most is easy to miss. Health reports dead-lettered deliveries by count and by the age of the oldest failure, grouped by channel account. A dead-letter count that only goes up tells you more about a broken integration than any single OK.

The "starting" result will fool your cron job

Startup shares a 60-second readiness window, which --timeout overrides. If the Gateway is still coming up when time runs out, health returns a non-failing result with "status": "starting" in JSON. Non-failing. A script that only checks the exit code will call a Gateway that never finished booting healthy, every time it runs right after a restart, which on a box that restarts nightly is exactly when you most want the check to work. Parse the JSON and treat starting as its own state, then retry. The cron automation guide covers scheduling the retry.

The HTTP endpoints, for things that are not you

All three are unauthenticated. Point external uptime services at /health, never at /v1/chat/completions. A chat completion ping creates a session and calls a model, so a monitor hitting it every minute quietly fills your session store with junk and bills you for the privilege. I would keep /ready for deploy gates rather than paging, since chat-recovery makes it fail for reasons that are fine.

Final verdict

Plain status for a glance. status --all when someone else has to read it. --deep only when a channel is lying to you, and health --verbose when you need the Gateway's answer from right now rather than from 60 seconds ago. For anything automated, parse JSON and handle starting explicitly. And when all of these say OK and the agent still will not answer, stop checking and start diagnosing, which is what the gateway doctor guide is for.