Skip to content

NOTIFICATION_CATEGORIZATION.md

Latest commit

 

History

History
137 lines (103 loc) · 4.85 KB

NOTIFICATION_CATEGORIZATION.md

File metadata and controls

137 lines (103 loc) · 4.85 KB

Notification Categorization

The tray app categorizes incoming notifications to apply per-category filters, display appropriate icons, and let users control which notifications they see.

How It Works

Notifications flow through a layered pipeline — the first layer that matches wins:

Structured Metadata  →  User Rules  →  Keyword Matching  →  Default (info)

1. Structured Metadata (highest priority)

If the gateway sends metadata on the notification, it is used directly:

  • Intent (e.g. reminder, build, alert) — maps to a category
  • Channel (e.g. email, calendar, ci) — maps to a category

This eliminates misclassification. A chat response that mentions "email" won't be categorized as email — the gateway knows the actual source.

Note: The gateway does not send structured metadata yet. When it does, categorization will automatically improve with no client changes needed.

2. User-Defined Rules

Custom regex or keyword rules, evaluated in order. Configure these in %APPDATA%\OpenClawTray\settings.json:

{
  "UserRules": [
    {
      "Pattern": "invoice|receipt",
      "IsRegex": true,
      "Category": "email",
      "Enabled": true
    },
    {
      "Pattern": "deploy to prod",
      "IsRegex": false,
      "Category": "urgent",
      "Enabled": true
    }
  ]
}

Rules match against both the notification title and message (case-insensitive). Invalid regex patterns are silently skipped.

3. Keyword Matching (legacy fallback)

The original keyword-based system, preserved for backward compatibility:

Category Keywords Icon
health blood sugar, glucose, cgm, mg/dl 🩸
urgent urgent, critical, emergency 🚨
reminder reminder ⏰
stock stock, in stock, available now 📦
email email, inbox, gmail 📧
calendar calendar, meeting, event 📅
error error, failed, exception ⚠️
build build, ci, deploy 🔨
info (everything else) 🤖

4. Default

If nothing matches, the notification is categorized as info.

Chat Response Toggle

Notifications are either chat responses (replies from an AI agent) or system notifications (alerts, reminders, build status, etc.). The NotifyChatResponses setting controls whether chat responses generate Windows toasts:

Setting Chat Responses System Notifications
true (default) ✅ Shown ✅ Shown
false ❌ Suppressed ✅ Shown

This is useful when you're having a conversation through another device and don't want every reply popping up as a toast on your desktop.

Settings

All notification settings are in %APPDATA%\OpenClawTray\settings.json:

{
  "ShowNotifications": true,
  "NotificationSound": "Default",

  "NotifyHealth": true,
  "NotifyUrgent": true,
  "NotifyReminder": true,
  "NotifyEmail": true,
  "NotifyCalendar": true,
  "NotifyBuild": true,
  "NotifyStock": true,
  "NotifyInfo": true,

  "NotifyChatResponses": true,
  "PreferStructuredCategories": true,
  "UserRules": []
}
Setting Type Default Description
ShowNotifications bool true Master toggle for all notifications
NotifyHealth bool true Show health/glucose alerts
NotifyUrgent bool true Show urgent alerts (also covers error type)
NotifyReminder bool true Show reminders
NotifyEmail bool true Show email notifications
NotifyCalendar bool true Show calendar events
NotifyBuild bool true Show build/CI/deploy notifications
NotifyStock bool true Show stock alerts
NotifyInfo bool true Show general info notifications
NotifyChatResponses bool true Show chat response toasts
PreferStructuredCategories bool true Use gateway metadata over keywords
UserRules array [] Custom categorization rules (see above)

Channel and Agent Mapping

When structured metadata is available, channels and agents map to categories:

Channel → Category:

Channel Category
calendar calendar
email email
ci, build build
stock, inventory stock
health health
alerts urgent

Agent mapping is also supported — per-agent category defaults can be added to the channel map in NotificationCategorizer.cs.

Architecture

The categorization logic lives in OpenClaw.Shared.NotificationCategorizer, making it available to both the WinUI tray app and any other consumers of the shared library. The gateway client (OpenClawGatewayClient) calls the categorizer when emitting notifications, and the tray app's ShouldShowNotification method applies the per-category and chat-toggle filters before showing a toast.
⚡