OpenClaw health checks

The docs’ health page is a short guide to verifying Gateway and channel health without guessing: the CLI checks, the HTTP probe endpoints, the dedicated health command, and uptime monitoring. Here are the quick checks, the deeper diagnostics, the health monitor and the restart ladder it waits for, the ingress failure domain that transport health does not cover, the three probes and which one an orchestrator should use, the monitoring rule that saves your session store, and the queue warnings hidden inside an ok snapshot.

Quick checks

• Status gives a local summary, reachability and mode, an update hint, linked channel auth age, sessions and recent activity; the all flag is the full read-only diagnosis, the deep flag asks the running Gateway for a live probe with per-account channel probes, and the usage flag shows provider usage and quota snapshots.
• Health asks the running Gateway for its snapshot over the WebSocket, never opening channel sockets from the CLI; verbose forces a live probe and prints connection details, and JSON gives a machine-readable snapshot. A standalone status command in any chat returns a status reply without invoking the agent.
• Session rows are not socket liveness: a provider can reconnect and show healthy before any new session row exists, so live connectivity comes from the channel status and health commands, not the sessions list. Per-agent counts cover that agent only, and the top-level session summary is the default agent, not a fleet total.
• Deep diagnostics: credential file times on disk, the per-agent session store, the relink flow for the 409 to 515 status codes or a logged-out marker, diagnostics on by default with memory, liveness and oversized-payload events that never record message text or secrets, a bounded stability recorder whose bundles persist after fatal exits, and a diagnostics export zip for bug reports with chat text, bodies, credentials and identifiers redacted.

External uptime monitoring services should use the dedicated /health endpoint, not /v1/chat/completions.

The health monitor and ingress

Health-monitor restarts can be disabled per channel or per account on the channels that expose the setting, Discord, Google Chat, iMessage, IRC, Teams, Signal, Slack, Telegram and WhatsApp; a crashing channel is recovered by its own auto-restart backoff first, ten attempts logged one by one, and the monitor stays out of the way until that ladder gives up, then takes over as the last restart owner. Channel connectivity and inbound admission are separate failure domains: a channel can hold a healthy transport and send replies normally while its durable ingress queue is unavailable, so not one inbound message is admitted. Such an account is unhealthy regardless of transport state, readiness reports it as failing, the channel status names the condition, and recovery is automatic through the ordinary restart path, logged with an ingress-unavailable reason; restarts that keep repeating mean the cause is not transient, for example a plugin denied the queue capability. Channels that never report ingress state are unaffected, because absence means no signal, never broken, and there is no traffic-staleness heuristic, so a quiet channel is never marked unhealthy for receiving nothing.

The three probes

• Health, at two paths, means the HTTP server is live: use it for process liveness and restart decisions. Startup, at two paths, means startup work is complete and the Gateway is not draining, with channel health not consulted: use it for orchestrator startup and traffic admission on Kubernetes, Fly, Render and similar, since it returns 503 while starting or draining and 200 once started.
• Ready, at two paths, adds deep readiness checks on configured channel accounts: use it for operator monitoring that should surface hard channel failures, since a broken Telegram account can make it return 503 without taking a healthy Control UI out of service through the startup probe. Unauthenticated remote responses contain only the ok flag and the status; local or authenticated callers also get the version, uptime and a pending reason, and readiness details follow the same gate because they can name failing subsystems.
• Detailed readiness can include an event-loop snapshot: a CPU core ratio measured across the whole process in core equivalents, so values above one mean parallel work, plus main-thread delay and utilisation; the Control UI’s busyness overlay reads the same sampler and shows a dash until the first window completes.

The OpenClaw doctor is the repair side of the same checks, and OpenClaw logs the stream the quick checks tell you to filter.

Uptime monitors and queue warnings

The monitoring rule has a reason: a request to the chat completions endpoint without a session header or user field creates a new random session with a skill snapshot, context assembly and model calls, so a monitor pinging every fifteen minutes creates about ninety-six sessions a day of four to twenty-two kilobytes each, bloating the store and eventually overflowing context, while the health endpoint answers instantly with no session and no model call. The health command returns a cached snapshot the Gateway refreshes in the background on a one-minute cadence, live probes use bounded account concurrency and a Gateway-owned deadline so one slow account returns a structured timeout, and the command exits non-zero when the Gateway is unreachable. A top-level ok means the snapshot was produced, not that every delivery queue is clear: the ingress-pressure field lists durable inbound lanes where an active row has reached eight attempts with a recorded error or a claim has gone unrefreshed for thirty minutes, grouped by channel account with pending, claimed and blocked counts and never any payload or identifier. OpenClaw not responding is the symptom-first walk through the same signals, and OpenClaw on Kubernetes the deployment where the startup probe is the readiness gate.

On Diali

On Diali the probes are ours to watch: the instance’s startup and readiness endpoints feed our monitoring, and the dashboard shows the assistant as running, updating or stopped from the same signals. Hosted OpenClaw on Diali is the assistant.

• Health for liveness, startup for admission, ready for operators.
• Transport healthy is not ingress healthy.
• Monitor the health endpoint, never the chat endpoint.