OpenClaw Health Checks: Stop Finding Out Your Agent Is Down From Users

The worst way to discover your OpenClaw agent is down is from a customer, teammate, or missed cron report. By then the technical problem has already turned into an operator-trust problem. The agent may be smart, the prompts may be good, and the tools may be wired correctly, but none of that matters if nobody notices the gateway stopped responding or a channel silently stopped delivering messages.

Health checks are not glamorous. They are revenue infrastructure. If an AI operator is supposed to answer customers, run follow-ups, publish content, triage alerts, or watch a workflow, the first job is proving the operating loop is alive. OpenClaw gives you enough surfaces to do that without guessing: status, gateway probes, health snapshots, doctor, channel probes, logs, cron run history, and heartbeat state.

This is the ladder I would use for a production-ish OpenClaw setup. It is deliberately boring. Start broad, prove the gateway is reachable, prove channels are healthy, inspect logs, then only repair the layer that actually failed.

Healthy does not mean “there is a session row”

A common operator mistake is treating stored session state as live channel proof. The OpenClaw health docs call this out directly: session lists and stored conversation rows are not socket liveness. A provider can reconnect and report healthy channel status before any new session row appears.

So the question is not, “Did I see a conversation in memory?” The question is, “Can the gateway respond, can the relevant channel probe pass, and do logs show message flow?” That distinction prevents a lot of pointless prompt edits.

For live checks, use the channel and health commands. For historical context, use session tools. Those are different jobs.

The 60-second ladder

The official troubleshooting page gives a practical first-minute sequence. I like it because it forces you to move from cheap read-only checks into deeper probes instead of restarting things blindly.

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

openclaw status is the fast local summary. The docs say it covers gateway reachability or mode, update hints, linked channel auth age, sessions, and recent activity. openclaw status --all expands that into a fuller local diagnosis that is meant to be safe to paste for debugging.

When you need live probes, use openclaw status --deep. The current docs say this asks the running gateway for a live health probe, including per-account channel probes when supported. That is the key jump from “the config exists” to “the transport looks alive.”

Then prove the gateway itself. openclaw gateway probe probes the configured remote gateway when one exists and localhost as well. It reports reachability, full RPC success, or degraded scope-limited detail RPC. The docs are clear that scope-limited detail RPC is degraded diagnostics, not necessarily a connection failure.

openclaw gateway status is the service/runtime view. It shows the managed service plus an optional RPC probe. If you are scripting a guardrail and a listening port is not enough, use --require-rpc so the command exits non-zero when the RPC probe fails.

Use openclaw health when you need machine-readable proof

openclaw health asks the running gateway for its health snapshot. The CLI docs list three useful forms:

openclaw health
openclaw health --json
openclaw health --verbose

The default command can return a fresh cached gateway health payload and refresh in the background. --verbose forces a live probe and prints gateway connection details. --json gives you machine-readable output, which is the version I would wire into any external monitor or cron sanity check.

My bias is simple: humans can read status; automation should read health --json. If you are deciding whether to page a person, skip a post, or suppress a risky automation, use structured output instead of scraping a pretty terminal screen.

Doctor is for repair, not superstition

openclaw doctor is the repair and migration tool. The docs say it fixes stale config and state, checks health, and provides actionable repair steps. It can normalize legacy config, move old state layouts, check gateway runtime problems, inspect permissions, warn about auth health, and detect service issues.

That does not mean “run the strongest doctor command whenever anything feels weird.” Start with diagnosis. If doctor reports a stale config migration, a service mismatch, or a gateway runtime issue, then choose the lightest repair mode that matches the situation.

openclaw doctor
openclaw doctor --non-interactive
openclaw doctor --repair

--non-interactive is the safer automation shape because it runs without prompts and only applies safe migrations, skipping restart or service actions that require human confirmation. --repair applies recommended repairs without prompting, including restarts where safe. --repair --force exists for aggressive repairs, but I would not put that in a routine unattended check.

If you want the operator version of this, health checks, memory discipline, cron follow-through, X safety, and production reporting in one place, get ClawKit here.

Logs tell you whether work is flowing

OpenClaw logs in two main places: console output and gateway file logs. The logging docs say the default rolling file lives under /tmp/openclaw/openclaw-YYYY-MM-DD.log, with JSON objects written one per line. The gateway host's local timezone controls the date in that file name.

The easiest way to read them is not tail over SSH. Use the CLI:

openclaw logs --follow
openclaw logs --json
openclaw logs --limit 500
openclaw logs --follow --local-time

openclaw logs tails gateway file logs over RPC, which also works in remote mode. --json is useful for tooling, and --local-time makes timestamps easier to read during incident review. If the gateway is unreachable, the logging overview says the CLI prints a hint to run openclaw doctor.

When a channel is quiet, do not just stare at the last assistant reply. Look for transport and policy signals. The health docs explicitly call out filters such as web-heartbeat, web-reconnect, web-auto-reply, and web-inbound for WhatsApp/WebChat-style debugging. Channel troubleshooting docs also mention signatures like mention gating, pairing, allowlist blocks, missing scopes, forbidden responses, and auth errors.

Channel health is its own layer

A gateway can be alive while one channel is dead. That is why the troubleshooting ladder includes:

openclaw channels status --probe
openclaw pairing list <channel>
openclaw logs --follow

The channel troubleshooting docs use the same baseline across providers: gateway runtime should be running, RPC probe should be okay, and the channel probe should show connected or ready. After that, provider-specific failures matter.

• Slack: check app token, bot token, scopes, DM pairing, group policy, and channel allowlist.
• Discord: check guild/channel allow rules, message content intent, mention gating, and DM pairing.
• Telegram: check pairing, bot privacy mode for groups, API network errors, and rejected bot-command setup.
• WhatsApp: check pairing, group mention policy, allowlists, and reconnect or relogin loops.

The important operator habit is to treat channel state as policy plus transport. “Connected” is not the same as “this sender is allowed, this group triggers replies, and the bot has permission to send there.”

Do not forget cron and heartbeat evidence

If the complaint is “the agent did not do the scheduled thing,” inspect the scheduler before blaming the model. The automation troubleshooting docs give this sequence:

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

Good cron evidence is concrete: enabled scheduler, future nextWakeAtMs, valid schedule and timezone, and recent run history with ok or an explicit skip reason. Common signatures include scheduler disabled, timer tick failures, manual run not-due, missing delivery targets, channel auth errors, or delivery mode set to none.

Heartbeat has different failure modes. The docs list quiet hours, requests in flight, empty heartbeat files, disabled alerts, invalid account IDs, and DM-blocking policy as common skip reasons. That matters because a silent heartbeat may be working exactly as configured.

If you run an operator box, make cron and heartbeat reports evidence-based. “It should have run” is not a diagnosis. “The run history says skipped because channel auth was forbidden” is a diagnosis.

Set health monitoring deliberately

OpenClaw also exposes channel health monitor configuration. The health docs list gateway.channelHealthCheckMinutes, gateway.channelStaleEventThresholdMinutes, and gateway.channelMaxRestartsPerHour. They also document per-channel and per-account health monitor overrides for built-in monitors such as Discord, Google Chat, iMessage, Microsoft Teams, Signal, Slack, Telegram, and WhatsApp.

I would not tune those numbers casually. The useful default posture is: let the gateway monitor channels, keep stale thresholds longer than the health-check interval, and cap restarts so a broken account does not thrash all day. If one provider is noisy, disable or adjust that specific channel/account instead of turning off monitoring globally.

The operator rule

When an OpenClaw agent looks down, follow the layers:

1. Fast summary with openclaw status.
2. Live gateway proof with openclaw gateway probe and gateway status.
3. Machine-readable health with openclaw health --json.
4. Repair guidance with openclaw doctor, not blind restarts.
5. Channel proof with channels status --probe and pairing checks.
6. Work-flow proof with cron runs, heartbeat state, and logs.

The short version: do not debug production agents by vibes. OpenClaw gives you enough evidence to know whether the gateway, channel, scheduler, or policy layer failed. Use the evidence first. Then repair the smallest layer that is actually broken.

Want the complete guide? Get ClawKit — $9.99