macOS health checks: gateway and channel status in the menu bar app
This page explains how the macOS app displays gateway and channel health states via a menu bar status dot and settings cards. It is intended for users who need to monitor link status and run on-demand probes.
Read this when
- Debugging mac app health indicators
Health checks on macOS
Reading the linked channel health state from the menu bar app.
Menu bar
Status dot:
- Green: linked and probe healthy.
- Orange: linked but a channel probe reports degraded or not connected.
- Red: not linked yet.
The secondary line shows "linked · auth 12m" or the failure reason. Selecting "Run Health Check Now" in the menu starts an on demand probe.
Settings
- General tab contains a Health card: status dot, summary line (link state and auth age), and an optional failure detail line, with Retry now and Open logs buttons.
- Channels tab shows per channel status and controls (login QR, logout, probe, last disconnect or error) for WhatsApp and Telegram.
How the probe works
The app calls the Gateway's health RPC over its existing WebSocket connection (not a CLI shell out) every 60 seconds and on demand. The RPC loads credentials and reports status without sending messages. The app caches the last good snapshot and the last error separately so the UI loads instantly and does not flicker while offline.
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 or web-reconnect.