Neura Market Logo

openclaw health: Gateway Health Snapshot via RPC

Learn how to use the openclaw health command to pull a health snapshot from the active Gateway via WebSocket RPC. This reference covers options, behavior, and verbose mode for live probes.

Read this when

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

openclaw health

Pull a health snapshot from the active Gateway via WebSocket RPC, without needing direct channel sockets from the CLI.

Options

FlagDefaultDescription
--jsonfalseEmit machine-readable JSON in place of text.
--timeout <ms>10000Timeout, in milliseconds, for the connection.
--verbosefalseEnforce a live probe and widen the output to every configured account and agent.
--debugfalseShortcut for --verbose.

Examples:

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

Behavior

  • When --verbose is absent, the Gateway may serve a cached snapshot (fresh for up to 60 seconds and identical to live channel runtime state), refreshing it in the background for the next requester.
  • With --verbose, a live probe is forced (per-channel account probes), Gateway connection details are printed, and the human-readable output expands to all configured accounts and agents rather than only the default agent.
  • The complete snapshot is always returned by --json: 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.
  • A top-level ok: true signals that the health RPC succeeded and the Gateway generated a snapshot. Queue warnings do not flip it to false.
  • Dead-lettered outbound or session deliveries, or inbound channel events, cause text output to report their counts and the oldest failure age. Inbound counts are broken down by channel account; use openclaw channels dead-letters to inspect or recover individual events.
  • An optional deliveryQueues.ingressPressure summarizes durable inbound lanes that could block subsequent events. It is grouped by channel account and never reveals event, lane, payload, error, owner, token, session, or target identifiers. For the precise qualification and counting semantics, refer to Gateway health.
338 words · updated Aug 16, 2026