Notifications: Browser and macOS Alerts in Control UI
Learn how to enable and test browser or macOS notifications from the OpenClaw Control UI. This page covers the Notifications settings, device activation, and status review.
Read this when
- Enabling notifications from Settings
- Troubleshooting browser or macOS notification permission
- Comparing Control UI notifications with mobile push
OpenClaw can alert you when your attention is needed, either in the browser hosting the Control UI or through native macOS notifications if you are using the OpenClaw macOS app. All of this is managed under Settings → Notifications: you can activate the current device, review its status, and trigger a test alert.
This page addresses those two interfaces. It does not govern channel reaction notifications, Android notification forwarding, or iOS background push, since the mobile apps handle their own push registration through dedicated node paths. Refer to iOS and Nodes for those details.
Which surface you get
The capabilities of the Notifications page vary based on where you access it:
| Where Settings is open | Transport | What you can do |
|---|---|---|
| Supported web browser or installed Control UI PWA | Browser Push API via the Control UI service worker | Grant permission, subscribe or unsubscribe this browser, send a test |
| OpenClaw macOS app | Native macOS notifications | Grant app permission, jump to System Settings when blocked, send a local test |
| Browser without Push API support | None | Status only; enable and test stay unavailable |
The macOS app intentionally relies on the native permission flow rather than browser push, since that is the notification mechanism your Mac already honors.
Enable browser notifications
- Launch the Control UI in a browser that supports service workers,
PushManager, and notifications. - Verify that the Control UI has an active connection to the Gateway.
- Navigate to Settings → Notifications and choose Enable notifications.
- Accept the browser's permission request.
- Click Send test, and a test notification should appear within a few seconds.
Under the hood, enabling creates a push subscription in the current browser and sends its endpoint and keys to the Gateway. The Gateway stores browser subscriptions and its VAPID signing key in state/openclaw.sqlite, with no openclaw.json key available for editing. Upon reconnection of the Control UI, the Gateway automatically reconciles existing subscriptions.
The Send test option instructs the Gateway to deliver a test message to every registered browser subscription. Unsubscribe first removes the current browser's endpoint from the Gateway, then performs a local unsubscribe.
Enable notifications in the macOS app
- In the OpenClaw macOS app, go to Settings → Notifications.
- While the permission displays Not requested, select Enable notifications.
- Approve the macOS permission prompt.
- Use Send test to generate a local OpenClaw notification.
When the permission reads Denied, macOS will not prompt again. Choose Open System Settings, grant notification access to OpenClaw there, and return to the app, which rechecks the permission upon regaining focus. This permission is managed by macOS, not by Gateway configuration.
Troubleshooting
Enable is unavailable
Either the browser is missing the required Web Push APIs, or the Control UI has lost its Gateway connection. Use an up-to-date browser, verify the Gateway link, and refresh the page.
Browser permission is blocked
A browser permission that has been denied cannot be reopened from this page. Grant notification access to the Control UI origin through the browser's site settings, then reload Settings.
Service worker is not ready
The Control UI gives its service worker up to 10 seconds to respond. If that interval expires shortly after an update, force-refresh the page. When an outdated worker persists, clear site data for the dashboard origin and reconnect.
Web Push asks for a Doctor migration
Execute openclaw doctor --fix while the Gateway is stopped. Web Push will not use the retired JSON stores until Doctor imports them into SQLite.