Skip to main content

​
Health checks on macOS

The macOS app reads channel health from the Gateway. Configured channels do not need a linked-session field to report a healthy state. Explicitly disabled accounts stay inactive and cannot provide a healthy fallback. The menu shows actionable health problems: an orange failure reason or a red login requirement. Healthy and pending states stay quiet. Opening the menu refreshes health on demand.

​
Settings

  • In Connection settings, Local Gateway shows a health row: status dot, channel summary, and an optional failure detail line, with Retry now and Open logs buttons.
  • Channels tab surfaces per-channel status and controls (login QR, logout, probe, last disconnect/error).
The health row uses these states:
  • Green: the selected linked or configured channel has no reported failure.
  • Orange: a channel or health request reports a failure. An unlinked channel also stays orange when another configured channel is healthy.
  • Red: linking is required and no healthy configured channel is available.
  • Gray: health is pending or the selected channel is disabled or not configured.
The summary can read “Telegram ready”, “Telegram running”, or “linked · auth 12m”. The app honors the Gateway’s startup and reconnect grace windows; transient transport flags alone do not mark a channel degraded. Reported failures such as a stale socket or unavailable inbound processing still take precedence over a ready-looking connection. A missing HTTP status does not by itself mean a timeout; the app preserves the Gateway’s reported probe error.

​
How health refresh works

The app calls the Gateway’s health RPC over its existing WebSocket connection (not a CLI shell-out) every ~60s and on demand. This reads the Gateway’s health snapshot; it does not request an active channel probe or send messages. The app caches the last good snapshot and the last error separately so the UI loads instantly and does not flicker while offline. The health row and Connected Instances pane follow the Primary Gateway. Switching Primary immediately clears the previous Gateway’s cached status; delayed replies from that Gateway cannot replace the new results. Reconnecting to the same Gateway retains its last good health snapshot while a fresh check runs. Connection errors stay with the Gateway that reported them.

​
When in doubt

Use the CLI flow in Gateway health (openclaw status, openclaw status --deep, openclaw health --json) and run openclaw logs --follow, filtering for web-heartbeat / web-reconnect.