Complete reference for openclaw health, fetching Gateway health snapshots, verbose provider probing, multi-agent session details, and targeting remote Gateways.
What does Openclaw Health do?
It queries the running Gateway over its local RPC connection and returns a health snapshot—a summary of whether the Gateway is up, which channels are connected, and (with –verbose) how those channels are actually performing with live probes.
It’s a faster, narrower diagnostic than the full Openclaw Doctor Commands and Uses; while health tells you the current live state in seconds, doctor performs a full system audit with repair options. Think of health as the equivalent of a quick pulse check before escalating to a deeper investigation with the doctor.
Choosing Between Openclaw Health and Openclaw Gateway Health
The top-level openclaw health command is a convenience alias for checking your local Gateway, it connects to the Gateway already running on your machine with no connection flags needed. If you need to check a remote Gateway (a VPS, a Tailnet node, or another machine), use openclaw gateway health with explicit –url, –token, or –password flags. See Remote Gateway for that pattern.
Commands & Flags
Three variants, basic snapshot, JSON output, and verbose live probing.
| openclaw healthread-only Fetches and prints the basic health snapshot from the running local Gateway. Returns channel connectivity state, Gateway version, and uptime. Use this as the first check when something feels wrong with message delivery or agent responses. |
| openclaw health –jsonmachine-readable Outputs the health snapshot in machine-readable JSON format. Use this when piping the output into scripts, monitoring systems, or CI health checks. |
| openclaw health –verboselive probes Provides a more detailed output. Runs live probes against configured providers, prints per-account timings when multiple accounts are configured, and displays the target URL and config path if any errors occur. Live provider probes: actively tests connectivity to each configured channel provider, not just cached state. Per-account timings: when multiple accounts are configured, shows response latency per account to identify slow or failing connections. Error context: on failures, prints the target URL and config path so you know exactly which endpoint and configuration entry is involved. |
all three variants
# Basic snapshot — quick pass/fail openclaw health # Machine-readable output for scripts and monitoring openclaw health --json # Full detail with live probes and per-account timings openclaw health --verbose
Multi-Agent Details
When multiple agents are configured, the health output automatically includes additional per-agent information.
If you have multiple agents configured, the health output will automatically include details about the per-agent session stores. This means you can see at a glance whether each agent’s session state is healthy, without needing to inspect them individually.
| Setup | What health output includes |
|---|---|
| Single agent | Overall Gateway state, channel connectivity, version and uptime. |
| Multiple agents | All of the above, plus per-agent session store details for each configured agent. Useful for identifying if one agent’s session state has drifted or failed without affecting others. |
| Multiple agents + –verbose | All of the above, plus live channel probes and per-account timings scoped per agent account where relevant. |
Remote Gateway Health
The top-level openclaw health always targets your local Gateway. To check a remote instance, use the gateway-scoped variant with explicit connection flags.
| openclaw gateway healthremote-capable The gateway-specific variant of the health command. Accepts explicit connection overrides to target any reachable Gateway instance, a VPS, Tailnet node, or remote machine. All the same output as openclaw health, just pointed at a different endpoint. –url ws://<host>:<port> | –token <token> | –password <password> |
local vs. remote health check
# Local Gateway — no connection flags needed openclaw health # Remote Gateway — explicit URL and auth required openclaw gateway health --url ws://<host>:<port> --token <token> # Remote Gateway with password auth openclaw gateway health --url ws://<host>:<port> --password <password> # Verbose probe against a remote instance openclaw gateway health --url ws://<host>:<port> --token <token> --verbose
When passing –url to openclaw gateway health, the CLI will not fall back to config or environment credentials, you must also explicitly pass –token or –password, or the command will fail with an auth error.
