---
summary: "Enable and test browser or macOS notifications from the Control UI"
title: "Notifications"
read_when:
  - Enabling notifications from Settings
  - Troubleshooting browser or macOS notification permission
  - Comparing Control UI notifications with mobile push
  - Enabling browser alerts when another person mentions you
---

OpenClaw can ping you when something needs your attention, including an exec or plugin approval request. The ping arrives in the browser that runs the Control UI. It can also arrive 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. Use the same page to 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](/platforms/ios) and [Nodes](/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 | Receive approvals and enabled attention categories, manage this browser's subscription, and 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. That includes sends from **New Session** or **Start in background**. The prompt appears once per browser and origin. **Settings → Notifications** remains the manual path for enabling or repairing notifications, including after you deny the automatic prompt.

1. Open the Control UI in a browser that supports service workers, `PushManager`, and notifications.
2. Make sure the Control UI is connected to the Gateway.
3. Open **Settings → Notifications** and select **Enable notifications**.
4. Allow notifications when the browser asks.
5. 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 binds the subscription to the browser's paired device and, when operator roles are enabled, its authenticated user profile. 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.

Approval notifications use generic lock-screen text. Command, working-directory, prompt, and plugin details stay out of the push payload. Selecting the notification opens the authenticated `/approve/<approvalId>` page. Before each send, the Gateway rechecks the paired device's current approval scopes, operator role, user profile, and approval visibility. A revoked or downgraded browser stops receiving approval pushes without needing to unsubscribe first.

### Choose what reaches each device

After subscribing, **Settings → Notifications** exposes two preference layers:

- **Account defaults** follow a durable authenticated user profile across devices. They control approval requests and updates, agent completion, agent questions, and human mentions. They also control scheduled-task failures, background-task failures, lock-screen detail, quiet hours, timezone, and an optional agent allowlist.
- **This browser or app** can mute one browser profile or installed Home Screen app. It can also add a source label or override individual categories. The account defaults stay unchanged. Native OpenClaw app notifications are configured separately.

Single-user Gateways use their durable owner profile for account defaults, so those preferences follow the owner across devices. Connections without a profile keep the controls but store preferences only with the current browser subscription. Preferences never grant access: every delivery still rechecks the paired device, current role and scopes, authenticated profile, and session visibility. Multi-user events without an authoritative session owner are suppressed instead of being broadcast to every operator.

By default, approval request and resolution notifications are enabled, and every other attention category is opt-in. Quiet hours suppress matching sends rather than queueing stale alerts for later delivery.

Selecting an attention notification opens its question, conversation, or automation run on the Gateway that produced it. **Agent finished** waits for completion. A parent waiting for child agents does not count as finished. Automation failures use **Scheduled task failures**, without also generating a **Background task failures** alert for the same run.

The detail levels are:

- **Private** — generic attention text only.
- **Names only** — may include a sanitized person, session, device, agent, task, or automation label.
- **Detailed** — currently uses the same bounded, sanitized producer-owned labels. Message excerpts, raw prompts, command arguments, output, environment values, and errors never enter the push payload.

On iPhone and iPad, Web Push is available only after two steps. First, install the Control UI with **Share → Add to Home Screen**. Then open that installed app. A normal Safari tab remains usable for the Control UI. In that tab, the Notifications page reports the install requirement. It does not attempt to dereference an unavailable `PushManager`.

**Send test** asks the Gateway to push a test message to every registered browser subscription. Tests intentionally check transport only. Approval requests are targeted to authorized device bindings. **Unsubscribe** removes the current browser's endpoint from the Gateway only when its paired device and user profile still own the subscription. It then unsubscribes locally. Reconnecting under another profile can transfer the browser subscription only with its existing subscription keys. Knowing an endpoint alone cannot change its owner or remove it.

The Gateway sends Web Push directly to the browser vendor's push service. This works with a self-hosted Gateway and does not use the OpenClaw-hosted iOS relay.

### Receive human mention alerts

After subscribing in a supported browser or installed Control UI PWA, turn on **Someone mentions me** under **Settings → Notifications**. The category is **off by default** and requires a signed-in Gateway profile. Account defaults can enable it across your devices. The current browser can override or mute it. These category controls appear for subscribed web clients, not the native macOS notification settings.

Only browsers bound to the mentioned profile receive the alert. Each delivery rechecks the device, current profile and role, read scope, and session visibility. It then applies the category setting, quiet hours, and agent filter. Being online is not required. With **Private** detail, the alert says only that someone mentioned you in a conversation. **Names only** and **Detailed** may include the sanitized sender and session labels, never the message excerpt. Selecting it opens the session through the normal authenticated Control UI route.

Your [mentions Inbox](/concepts/multi-user#temporary-mentions-inbox) does not depend on Web Push permission or this setting. Its entries and dismissals survive Gateway restarts within the seven-day retention window. Opening the Inbox, reconnecting, or restarting the Gateway does not resend old entries as browser notifications. The service worker shows browser alerts. The live Inbox update does not create a second OS notification. Human mention alerts are not implemented through the native macOS or iOS/Android push paths.

To check targeting, have another eligible signed-in person select you from the chat `@` picker and send a normal message. Check **Inbox → Mentions**, then check the enabled browser alert. **Send test** only checks browser push transport and can reach every registered subscription. It does not prove that a human mention was selected, committed, or addressed to your profile. Delivery is best-effort, not an exactly-once guarantee.

### Use more than one Gateway on one phone

The recommended self-hosted setup is one Control UI service-worker scope per Gateway. Open or install each Gateway's PWA from its own HTTPS origin or base path. Enable notifications there. Reconnect once after upgrades. Each scope then owns an independent browser subscription, and approval links return to the Gateway that created them.

A single installed PWA can also switch among remote Gateways. Every Gateway behind that PWA must then use the same VAPID keypair. Each must also set `gateway.publicOrigin` to its browser-reachable HTTPS origin. Reconnect the PWA to each Gateway once so each one registers the shared browser subscription and current device/profile binding. Approval notification links stay inside the installed PWA's scope and carry the owning Gateway URL in their fragment. The Control UI removes the fragment before authentication and uses the normal remote-Gateway handoff.

The browser Push API permits only one application-server key per service-worker registration. If a PWA subscription belongs to a different VAPID key, OpenClaw removes the unusable row from the current Gateway. OpenClaw also shows **Unavailable** and **Not subscribed**, with an error explaining the mismatch. To switch that PWA scope to the current Gateway, select **Unsubscribe**, then **Enable notifications** and **Send test**. Unsubscribing deactivates the shared browser subscription for every Gateway registered through that scope. After re-enabling, reconnect to each Gateway once.

Sharing a private VAPID key and browser endpoint makes those Gateways one push-signing trust domain. Use that layout only for Gateways you trust equally. Configure VAPID values through each Gateway process's secure environment or secret manager. Do not place private keys in URLs or command arguments.

## 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.

1. Open **Settings → Notifications** in the OpenClaw macOS app.
2. Select **Enable notifications** while the permission shows **Not requested**.
3. Approve the macOS permission prompt.
4. 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. Then switch back. The page rechecks permission when the app regains focus. This permission belongs to macOS, not to Gateway config.

### Background session completion

You can start a session in the background from **New Session**. The macOS app then posts a native notification after that run finishes. This requires notification permission to be already granted. Keep the originating dashboard loaded while it runs. You can minimize its window or work in another app. An in-app completion message also appears. Selecting the session before it finishes suppresses its completion notice.

The native notification uses generic text, without the session title, prompt, or response. Select it to open the session on its originating Gateway, including when that window has since closed. If that Gateway connection changed, open the session from the correct Gateway's session list instead. Do the same if the notification expired after an app restart.

This is the **New Session** background-start flow, not a native notification for every chat response. Browser **Agent finished** preferences remain separate. Completing a background run never opens a new permission prompt. Enable notifications in Settings first.

## 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, check 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.

### Permission is granted but the browser is not subscribed

Browser permission and the Gateway subscription are separate. Select **Enable notifications** to register this browser, then enable the categories you want, such as **Someone mentions me**. Reloading or sending another message does not automatically subscribe a browser whose permission is already granted. This preserves an intentional unsubscribe.

### 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.

### Tests arrive but approval requests do not

Reconnect or reload the Control UI once so an older subscription is bound to the current paired device. The device must still have `operator.approvals` and `operator.read`. When Gateway roles are enabled, the current user profile's role must allow those scopes too. Approval visibility and session-sharing rules can intentionally exclude a request that the same Gateway sends to another operator.

For a single PWA that switches among Gateways, also check two things. Every Gateway must use the same VAPID keypair. Every Gateway must have a browser-reachable `gateway.publicOrigin`. Separate PWA origins or base-path scopes do not need to share VAPID keys.

### A mention is missing or produces no browser alert

Check that the sender selected your profile from the picker, rather than only typing your name. Check that the original message reached the transcript. Sign in with the same profile and check that you still have access to the session. Incognito, Goal, catalog, suggestion-only, and command-send modes do not support human mentions.

If the entry is in **Inbox → Mentions**, check this browser's subscription and **Someone mentions me**. Also check quiet hours, mute overrides, and the agent filter. An Inbox entry does not imply permission to show a browser notification. If the entry disappeared, it may have been dismissed from another browser using your profile. It may also have expired, been evicted, or become inaccessible after a session access change. Gateway restarts preserve retained entries and dismissals. The retained chat message is independent of the Inbox entry. Entries already lost before durable storage was introduced are not recovered from old messages.

## Related

- [Control UI PWA and Web Push](/web/control-ui/connect-and-pair#pwa-install-and-web-push)
- [iOS push delivery](/platforms/ios)
- [Node notification commands](/nodes)