OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

Health

openclaw health

Fetch a health snapshot from the running Gateway over WebSocket RPC (no direct channel sockets from the CLI).

Options

Flag Default Description
--json false Print machine-readable JSON instead of text.
--timeout <ms> 10000 Connection timeout in milliseconds.
--verbose false Forces a live probe and expands output across all configured accounts and agents.
--debug false Alias for --verbose.

Examples:

bash
openclaw healthopenclaw health --jsonopenclaw health --timeout 2500openclaw health --verboseopenclaw health --debug

Behavior

  • Without --verbose, the Gateway can return a cached snapshot and refresh it in the background for the next caller. A cached snapshot is fresh for up to 60 seconds and unchanged from live channel runtime state.
  • --verbose forces a live probe of each channel account. It also prints Gateway connection details. It expands human-readable output across all configured accounts and agents, instead of just the default agent.
  • An unconfigured or disabled preferred account does not hide probe results from other active accounts. Ordinary output still follows the default agent's account bindings. --verbose includes all accounts.
  • When the displayed account is disabled, health text shows disabled and status --deep marks it OFF, even if the account remains configured.
  • Unhealthy channel lines include the recorded startup error when available, so a stopped channel reports its failure cause alongside its state.
  • --json always returns the full snapshot: channels, per-account probes, plugin load state, context-engine quarantine state, model-pricing cache state, event-loop health, delivery-queue warnings, and per-agent session stores.
  • Session ages in text and JSON use the Gateway's clock.
  • Heartbeat intervals in text show the resolved cadence without rounding away milliseconds. Week units are retained for long intervals.
  • Top-level ok: true means the health RPC succeeded and the Gateway produced a snapshot. Queue warnings do not change it to false.
  • When outbound or session deliveries, or inbound channel events, are dead-lettered, text output reports their counts and oldest failure age. Inbound counts are grouped by channel account. Inspect or recover individual events with openclaw channels dead-letters.
  • Optional deliveryQueues.ingressPressure summarizes durable inbound lanes that may be blocking later events. It is grouped by channel account and never exposes event, lane, payload, error, owner, token, session, or target identifiers. See Gateway health for the exact qualification and counting semantics.
Was this useful?
On this page

On this page