From 1549ded4ac0597f5f1faca06b8324244ede4cbec Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Sat, 25 Apr 2026 03:40:24 -0700 Subject: [PATCH] docs(control-ui): document PWA install and web push MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Eduardo Cruz's PWA web push feat (21b7ad5805, #44590) added a substantial user-facing surface — manifest.webmanifest, sw.js, gateway push.web.* methods, persisted vapid-keys.json/web-push-subscriptions.json, and OPENCLAW_VAPID_* env overrides — but did not touch any docs/. Add a 'PWA install and web push' section to docs/web/control-ui.md covering the new persisted state files, env vars, and the four scope-gated gateway methods (push.web.vapidPublicKey, push.web.subscribe, push.web.unsubscribe, push.web.test). Distinguish from the existing APNS relay-backed iOS push path. --- docs/web/control-ui.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md index 82521d904d9..4e7ec96bc4d 100644 --- a/docs/web/control-ui.md +++ b/docs/web/control-ui.md @@ -187,6 +187,40 @@ Cron jobs panel notes: - Gateway persists aborted partial assistant text into transcript history when buffered output exists - Persisted entries include abort metadata so transcript consumers can tell abort partials from normal completion output +## PWA install and web push + +The Control UI ships a `manifest.webmanifest` and a service worker, so +modern browsers can install it as a standalone PWA. Web Push lets the +Gateway wake the installed PWA with notifications even when the tab or +browser window is not open. + +| Surface | What it does | +| ----------------------------------------------------- | ------------------------------------------------------------------ | +| `ui/public/manifest.webmanifest` | PWA manifest. Browsers offer "Install app" once it is reachable. | +| `ui/public/sw.js` | Service worker that handles `push` events and notification clicks. | +| `push/vapid-keys.json` (under the OpenClaw state dir) | Auto-generated VAPID keypair used to sign Web Push payloads. | +| `push/web-push-subscriptions.json` | Persisted browser subscription endpoints. | + +Override the VAPID keypair through env vars on the Gateway process when +you want to pin keys (for multi-host deployments, secrets rotation, or +tests): + +- `OPENCLAW_VAPID_PUBLIC_KEY` +- `OPENCLAW_VAPID_PRIVATE_KEY` +- `OPENCLAW_VAPID_SUBJECT` (defaults to `mailto:openclaw@localhost`) + +The Control UI uses these scope-gated Gateway methods to register and +test browser subscriptions: + +- `push.web.vapidPublicKey` — fetches the active VAPID public key. +- `push.web.subscribe` — registers an `endpoint` plus `keys.p256dh`/`keys.auth`. +- `push.web.unsubscribe` — removes a registered endpoint. +- `push.web.test` — sends a test notification to the caller's subscription. + +Web Push is independent of the iOS APNS relay path +(see [Configuration](/gateway/configuration) for relay-backed push) and +the existing `push.test` method, which target native mobile pairing. + ## Hosted embeds Assistant messages can render hosted web content inline with the `[embed ...]`