Peter Steinberger
87ecc4085d
* feat(webui): auto-request notification permission on first chat send The Control UI now asks for notification permission automatically on the first chat message you send (once per browser/origin; web push in browsers, native prompt in the macOS app; denied permission is never re-asked automatically — Settings -> Notifications stays the manual path). * fix(webui): preserve notification prompt gesture boundary Restrict the one-shot notification prompt to direct non-command composer sends, invoke browser permission synchronously, and keep Settings documented as the management and recovery path. * fix(webui): exclude deferred notification sends Require an actively dispatching browser input event before consuming the notification one-shot, so retained catalog handoffs and other deferred sends cannot suppress the first real composer prompt.
5.0 KiB
summary, title, read_when
| summary | title | read_when | |||
|---|---|---|---|---|---|
| Enable and test browser or macOS notifications from the Control UI | Notifications |
|
OpenClaw can ping you when something needs your attention — in the browser that runs the Control UI, or through native macOS notifications when you use the OpenClaw macOS app. Your first chat send may request permission automatically; Settings → Notifications remains the place to enable or repair the current device, check its status, and send yourself a test.
This page covers those two surfaces. It does not control channel reaction notifications, Android notification forwarding, or iOS background push — the mobile apps register for push through their own node paths; see iOS and Nodes.
Which surface you get
What the Notifications page controls depends on where you opened 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 deliberately uses the native permission flow instead of browser push — that is the notification system your Mac already respects.
Enable browser notifications
The Control UI asks for notification permission automatically the first time you send a chat message, once per browser and origin. Settings → Notifications remains the manual path for enabling or repairing notifications, including after you deny the automatic prompt.
- Open the Control UI in a browser that supports service workers,
PushManager, and notifications. - Make sure the Control UI is connected to the Gateway.
- Open Settings → Notifications and select Enable notifications.
- Allow notifications when the browser asks.
- Select Send test — a test notification should arrive within a few seconds.
Behind the scenes, enabling creates a push subscription in this browser and registers its endpoint and keys with the Gateway. The Gateway keeps browser subscriptions and its VAPID signing key in state/openclaw.sqlite — there is no openclaw.json key to edit. When the Control UI reconnects, existing subscriptions are reconciled with the Gateway automatically.
Send test asks the Gateway to push a test message to every registered browser subscription. Unsubscribe removes the current browser's endpoint from the Gateway, then unsubscribes locally.
Enable notifications in the macOS app
The macOS app also asks automatically on your first chat send, but only while permission is Not requested. It never opens System Settings automatically after a denial; use Settings → Notifications to manage permission manually.
- Open Settings → Notifications in the OpenClaw macOS app.
- Select Enable notifications while the permission shows Not requested.
- Approve the macOS permission prompt.
- Select Send test to post a local OpenClaw notification.
If the permission shows Denied, macOS will not re-prompt: select Open System Settings, allow notifications for OpenClaw there, and switch back — the page rechecks permission when the app regains focus. This permission belongs to macOS, not to Gateway config.
Troubleshooting
Enable is unavailable
Either the browser lacks the required Web Push APIs or the Control UI is not connected to the Gateway. Try a current browser, confirm the Gateway connection, and reload the page.
Browser permission is blocked
A denied browser permission cannot be reopened from the page. Allow notifications for the Control UI origin in the browser's site settings, then reload Settings.
Service worker is not ready
The Control UI waits up to 10 seconds for its service worker. If that times out right after an update, hard-refresh the page. If an old worker sticks around, clear site data for the dashboard origin and reconnect.
Web Push asks for a Doctor migration
Run openclaw doctor --fix with the Gateway stopped. Web Push refuses to use the retired JSON stores until Doctor imports them into SQLite.