Neura Market Logo

openclaw health CLI command: Gateway health snapshot via WebSocket RPC

Reference for the openclaw health command, which retrieves a health snapshot from the active Gateway using WebSocket RPC. This page covers options, behavior, and examples for developers and operators.

Read this when

  • You want to quickly check the running Gateway's health

openclaw health

Retrieve a health snapshot from the active Gateway using WebSocket RPC (no direct channel sockets from the CLI).

Options

FlagDefaultDescription
--jsonfalseOutput machine-readable JSON instead of plain text.
--timeout <ms>10000Connection timeout measured in milliseconds.
--verbosefalseTriggers a live probe and expands output across every configured account and agent.
--debugfalseShort form of --verbose.

Examples:

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

Behavior

  • Without --verbose, the Gateway may return a cached snapshot (fresh for up to 60 seconds and identical to live channel runtime state) and refresh it in the background for the next caller.
  • --verbose forces a live probe (per-channel account probes), shows Gateway connection details, and expands human-readable output across every configured account and agent rather than only the default agent.
  • --json always returns the complete snapshot: channels, per-account probes, plugin load state, context-engine quarantine state, model-pricing cache state, event-loop health, delivery-queue dead letters, and per-agent session stores.
  • When outbound deliveries or inbound channel events are dead-lettered, text output reports their counts and the oldest failure age. Inbound counts are grouped by channel account; inspect or recover individual events with openclaw channels dead-letters.