macOS Health Checks: Gateway and Channel Status Monitoring
This page explains how the macOS app displays gateway and channel health states via a menu bar status dot and settings panels. It is intended for users who need to monitor link status and troubleshoot connectivity issues.
Read this when
- Debugging mac app health indicators
Health checks on macOS
Checking the linked channel health status from the menu bar app.
Menu bar
Status dot:
- Green: link established, probe indicates healthy.
- Orange: link established, but a channel probe reports degraded or disconnected.
- Red: link not yet established.
The secondary line shows "linked · auth 12m" or displays the failure cause. Selecting "Run Health Check Now" from the menu starts an immediate probe.
Settings
- The General tab contains a Health card with a status dot, a summary line (link state and auth age), and an optional failure detail line. It also provides Retry now and Open logs buttons.
- The 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 application invokes the Gateway's health RPC over the existing WebSocket connection (not through a CLI shell command) approximately every 60 seconds and on demand. This RPC loads credentials and reports status without transmitting messages. The app caches the most recent healthy snapshot and the latest error separately, so the UI loads instantly and avoids flickering when offline.
When in doubt
Use the CLI procedure described in Gateway health (openclaw status, openclaw status --deep, openclaw health --json) and execute openclaw logs --follow, filtering for web-heartbeat or web-reconnect.