UI Patcher (bundled extension)

This extension applies a prebuilt custom dist/control-ui bundle when enabled.

Behavior

• On gateway start: backs up current dist/control-ui to plugin state and applies patched UI.
• On gateway stop: restores original dist/control-ui from backup (default behavior).
• WAHA isolation: if extensions/waha is detected, UI patch apply is skipped; if a prior patch was active, original UI is restored.
• Runtime UI overrides:
  • Chat watermark URL/opacity/size from plugin config
  • WhatsApp guide button opens a new chat message prompt
  • Extra Shepherd tutorial button with config-driven steps

Config

{
  "plugins": {
    "entries": {
      "ui-patcher": {
        "enabled": true,
        "config": {
          "enabled": true,
          "autoRestoreOnStop": true,
          "watermarkUrl": "https://finaltouch.whatsynaptic.com/assets/brand-logo-uBqNKeuY.gif",
          "watermarkOpacity": 0.22,
          "watermarkWidth": "220px",
          "guidePrompt": "help me log into WhatsApp",
          "tutorialButtonLabel": "UI Tutorial",
          "tourSteps": [
            {
              "id": "channels",
              "title": "Channels",
              "text": "Manage account linking and channel health here.",
              "selector": "[data-tour-tab=\"channels\"]",
              "position": "bottom"
            },
            {
              "id": "show-qr",
              "title": "Show QR",
              "text": "Click Show QR to generate a pairing code for first-time WhatsApp login.",
              "selector": "[data-tour=\"whatsapp-show-qr\"]",
              "position": "bottom"
            },
            {
              "id": "scan-qr",
              "title": "Scan QR",
              "text": "Scan this QR in WhatsApp on your phone to complete linking.",
              "selector": "[data-tour=\"whatsapp-qr\"]",
              "position": "top"
            }
          ]
        }
      }
    }
  }
}

Quick Install Script

From inside extracted ui-patcher directory:

./scripts/install-ui-patcher.sh

Profile/state examples:

./scripts/install-ui-patcher.sh --profile dev
./scripts/install-ui-patcher.sh --state-dir /data/.openclaw
OPENCLAW_STATE_DIR=/data/.openclaw ./scripts/install-ui-patcher.sh
OPENCLAW_CONFIG_PATH=/data/.openclaw/openclaw.json ./scripts/install-ui-patcher.sh

What it does:

• checks for jq, installs it if missing
• copies plugin files to ~/.openclaw/extensions/ui-patcher
• enables ui-patcher in ~/.openclaw/openclaw.json
• prints restart command (openclaw gateway restart)

Notes

• This patches built artifacts directly and is intended for custom/self-hosted workflows.
• If you run pnpm ui:build while gateway is running, restart gateway to re-apply patch.