feat: implement wa-guardian for automated WhatsApp pairing and add Control UI shortcut to dashboard

.env.example

@@ -142,9 +142,6 @@ TELEGRAM_USER_ID=123456789
 # Multiple user IDs (comma-separated for team access)
 # TELEGRAM_USER_IDS=123456789,987654321,555555555
 
-# WhatsApp integration (pairing mode via CLI)
-# WHATSAPP_ENABLED=true
-
 # ── OPTIONAL: Workspace Backup to HF Dataset ──
 HF_USERNAME=your_hf_username
 HF_TOKEN=hf_your_token_here
@@ -164,9 +161,8 @@ KEEP_ALIVE_INTERVAL=300
 # Workspace auto-sync interval (seconds). Default: 600.
 SYNC_INTERVAL=600
 
-# ── OPTIONAL: Webhooks ──
-# URL to send HTTP POST requests on startup and backup errors
-# WEBHOOK_URL=https://your-webhook-endpoint.com/webhook
+# Webhooks: Standard POST notifications for lifecycle events
+# WEBHOOK_URL=https://your-webhook-endpoint.com/log
 
 # ── OPTIONAL: Advanced ──
 # Pin OpenClaw version. Default: latest

README.md

@@ -95,18 +95,9 @@ After restarting, the bot should appear online on Telegram.
 
 To use WhatsApp:
 
-1. Add the secret `WHATSAPP_ENABLED` and set it to `true`.
-2. Once the Space restarts, use the OpenClaw CLI to link your account:
-
-   ```bash
-   npm install -g openclaw@latest
-   openclaw channels login --gateway https://YOUR_SPACE_URL.hf.space --channel whatsapp
-   ```
-
-3. Scan the QR code with your phone (WhatsApp → Linked Devices).
-
-> [!NOTE]
-> HuggingClaw uses dynamic DNS-over-HTTPS probing to ensure reliability on HuggingFace Spaces.
+1. Visit your Space's Dashboard (Port 7861) and click **🚀 Open Control UI**.
+2. In the Control UI, go to **Channels** → **WhatsApp** → **Login**.
+3. Scan the QR code with your phone. 📱
 
 ## 💾 Workspace Backup *(Optional)*
 

health-server.js

@@ -1,50 +1,67 @@
 // Lightweight health server and dashboard on port 7861
-const http = require('http');
-const fs = require('fs');
-const path = require('path');
+const http = require("http");
+const fs = require("fs");
 
 const PORT = process.env.HEALTH_PORT || 7861;
 const startTime = Date.now();
-const LLM_MODEL = process.env.LLM_MODEL || 'Not Set';
-const WHATSAPP_ENABLED = process.env.WHATSAPP_ENABLED === 'true' || process.env.WHATSAPP_ENABLED === '1';
+const LLM_MODEL = process.env.LLM_MODEL || "Not Set";
+const GATEWAY_TOKEN = process.env.GATEWAY_TOKEN || "huggingclaw";
+const SPACE_HOST = process.env.SPACE_HOST || "localhost:7860";
 const TELEGRAM_ENABLED = !!process.env.TELEGRAM_BOT_TOKEN;
 
 const server = http.createServer((req, res) => {
   const uptime = Math.floor((Date.now() - startTime) / 1000);
   const uptimeHuman = `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m`;
 
-  if (req.url === '/health') {
-    res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({
-      status: 'ok',
-      uptime: uptime,
-      uptimeHuman: uptimeHuman,
-      timestamp: new Date().toISOString()
-    }));
+  if (req.url === "/health") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        status: "ok",
+        uptime: uptime,
+        uptimeHuman: uptimeHuman,
+        timestamp: new Date().toISOString(),
+      }),
+    );
     return;
   }
 
-  if (req.url === '/status') {
-    let syncStatus = { status: 'unknown', message: 'No sync data yet' };
+  if (req.url === "/status") {
+    let syncStatus = { status: "unknown", message: "No sync data yet" };
     try {
-      if (fs.existsSync('/tmp/sync-status.json')) {
-        syncStatus = JSON.parse(fs.readFileSync('/tmp/sync-status.json', 'utf8'));
+      if (fs.existsSync("/tmp/sync-status.json")) {
+        syncStatus = JSON.parse(
+          fs.readFileSync("/tmp/sync-status.json", "utf8"),
+        );
       }
     } catch (e) {}
-    
-    res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({
-      model: LLM_MODEL,
-      whatsapp: WHATSAPP_ENABLED,
-      telegram: TELEGRAM_ENABLED,
-      sync: syncStatus,
-      uptime: uptimeHuman
-    }));
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        model: LLM_MODEL,
+        whatsapp: true,
+        telegram: TELEGRAM_ENABLED,
+        sync: syncStatus,
+        uptime: uptimeHuman,
+        token: GATEWAY_TOKEN,
+      }),
+    );
+    return;
+  }
+
+  // Auto-login redirect to OpenClaw Control UI
+  if (req.url === "/login") {
+    const protocol = req.headers["x-forwarded-proto"] || "http";
+    const host = req.headers["host"] || SPACE_HOST;
+    const target = `${protocol}://${host}/?token=${GATEWAY_TOKEN}`;
+    res.writeHead(302, { Location: target });
+    res.end();
     return;
   }
 
-  if (req.url === '/') {
-    res.writeHead(200, { 'Content-Type': 'text/html' });
+  if (req.url === "/") {
+    res.writeHead(200, { "Content-Type": "text/html" });
     res.end(`
 <!DOCTYPE html>
 <html lang="en">
@@ -153,6 +170,25 @@ const server = http.createServer((req, res) => {
             word-break: break-all;
         }
 
+        .stat-btn {
+            grid-column: span 2;
+            background: var(--accent);
+            color: #fff;
+            padding: 16px;
+            border-radius: 16px;
+            text-align: center;
+            text-decoration: none;
+            font-weight: 600;
+            margin-top: 10px;
+            transition: transform 0.3s ease, box-shadow 0.3s ease;
+            box-shadow: 0 10px 20px -5px rgba(59, 130, 246, 0.4);
+        }
+
+        .stat-btn:hover {
+            transform: scale(1.02);
+            box-shadow: 0 15px 30px -5px rgba(59, 130, 246, 0.6);
+        }
+
         .status-badge {
             display: inline-flex;
             align-items: center;
@@ -226,6 +262,7 @@ const server = http.createServer((req, res) => {
                 <span class="stat-label">Telegram</span>
                 <span id="tg-status">Loading...</span>
             </div>
+            <a href="/login" class="stat-btn">🚀 Open Control UI</a>
         </div>
 
         <div class="stat-card" style="width: 100%;">
@@ -297,6 +334,6 @@ const server = http.createServer((req, res) => {
   res.end();
 });
 
-server.listen(PORT, '0.0.0.0', () => {
+server.listen(PORT, "0.0.0.0", () => {
   console.log(`🏥 Health server & Dashboard listening on port ${PORT}`);
 });

start.sh

@@ -235,10 +235,8 @@ if [ -n "$TELEGRAM_BOT_TOKEN" ]; then
 fi
 
 # WhatsApp
-if [ "$WHATSAPP_ENABLED" = "true" ] || [ "$WHATSAPP_ENABLED" = "1" ]; then
-  CONFIG_JSON=$(echo "$CONFIG_JSON" | jq '.plugins.entries.whatsapp = {"enabled": true}')
-  CONFIG_JSON=$(echo "$CONFIG_JSON" | jq '.channels.whatsapp = {"dmPolicy": "pairing"}')
-fi
+CONFIG_JSON=$(echo "$CONFIG_JSON" | jq '.plugins.entries.whatsapp = {"enabled": true}')
+CONFIG_JSON=$(echo "$CONFIG_JSON" | jq '.channels.whatsapp = {"dmPolicy": "pairing"}')
 
 # Write config
 echo "$CONFIG_JSON" > "/home/node/.openclaw/openclaw.json"
@@ -255,11 +253,7 @@ printf "  │  %-40s │\n" "Telegram: ✅ enabled"
 else
 printf "  │  %-40s │\n" "Telegram: ❌ not configured"
 fi
-if [ "$WHATSAPP_ENABLED" = "true" ] || [ "$WHATSAPP_ENABLED" = "1" ]; then
 printf "  │  %-40s │\n" "WhatsApp: ✅ enabled"
-else
-printf "  │  %-40s │\n" "WhatsApp: ❌ not configured"
-fi
 if [ -n "$HF_USERNAME" ] && [ -n "$HF_TOKEN" ]; then
 printf "  │  %-40s │\n" "Backup: ✅ ${HF_USERNAME}/${BACKUP_DATASET:-huggingclaw-backup}"
 else
@@ -323,10 +317,17 @@ trap graceful_shutdown SIGTERM SIGINT
 
 # ── Start background services ──
 export LLM_MODEL="$LLM_MODEL"
+# 10. Start Health Server & Dashboard
 node /home/node/app/health-server.js &
-/home/node/app/keep-alive.sh &
+HEALTH_PID=$!
+
+# 11. Start WhatsApp Guardian (Automates pairing)
+node /home/node/app/wa-guardian.js &
+GUARDIAN_PID=$!
+echo "🛡️ WhatsApp Guardian started (PID: $GUARDIAN_PID)"
 
-python3 /home/node/app/workspace-sync.py &
+# 12. Start Workspace Sync
+python3 -u /home/node/app/workspace-sync.py &
 
 # ── Launch gateway ──
 echo "🚀 Launching OpenClaw gateway on port 7860..."

wa-guardian.js

@@ -0,0 +1,126 @@
+/**
+ * HuggingClaw WhatsApp Guardian
+ *
+ * Automates the WhatsApp pairing process on HuggingFace Spaces.
+ * Handles the "515 Restart" by monitoring the channel status and
+ * re-applying the configuration after a successful scan.
+ */
+"use strict";
+
+const { WebSocket } = require('/home/node/.openclaw/openclaw-app/node_modules/ws');
+const { randomUUID } = require('node:crypto');
+
+const GATEWAY_URL = "ws://127.0.0.1:7860";
+const GATEWAY_TOKEN = process.env.GATEWAY_TOKEN || "huggingclaw";
+const CHECK_INTERVAL = 5000;
+const WAIT_TIMEOUT = 120000;
+
+let isWaiting = false;
+let hasShownWaitMessage = false;
+
+async function createConnection() {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(GATEWAY_URL);
+    let resolved = false;
+
+    ws.on("message", (data) => {
+      const msg = JSON.parse(data.toString());
+
+      if (msg.type === "event" && msg.event === "connect.challenge") {
+        ws.send(JSON.stringify({
+          type: "req",
+          id: randomUUID(),
+          method: "connect",
+          params: {
+            auth: { token: GATEWAY_TOKEN },
+            client: { id: "wa-guardian", platform: "linux", mode: "backend", version: "1.0.0" },
+            scopes: ["operator.admin", "operator.pairing", "operator.read", "operator.write"]
+          }
+        }));
+        return;
+      }
+
+      if (!resolved && msg.type === "res" && msg.ok) {
+        resolved = true;
+        resolve(ws);
+      }
+    });
+
+    ws.on("error", (e) => { if (!resolved) reject(e); });
+    setTimeout(() => { if (!resolved) { ws.close(); reject(new Error("Timeout")); } }, 10000);
+  });
+}
+
+async function callRpc(ws, method, params) {
+  return new Promise((resolve, reject) => {
+    const id = randomUUID();
+    const handler = (data) => {
+      const msg = JSON.parse(data.toString());
+      if (msg.id === id) {
+        ws.removeListener("message", handler);
+        resolve(msg);
+      }
+    };
+    ws.on("message", handler);
+    ws.send(JSON.stringify({ type: "req", id, method, params }));
+    setTimeout(() => { ws.removeListener("message", handler); reject(new Error("RPC Timeout")); }, WAIT_TIMEOUT + 5000);
+  });
+}
+
+async function checkStatus() {
+  if (isWaiting) return;
+
+  let ws;
+  try {
+    ws = await createConnection();
+
+    // Check if WhatsApp channel exists and its status
+    const statusRes = await callRpc(ws, "channels.status", {});
+    const channels = (statusRes.payload || statusRes.result)?.channels || {};
+    const wa = channels.whatsapp;
+
+    if (!wa) {
+      ws.close();
+      return;
+    }
+
+    // If connected, we are good
+    if (wa.connected) {
+      ws.close();
+      return;
+    }
+
+    // If "Ready to pair", we wait for the scan
+    isWaiting = true;
+    if (!hasShownWaitMessage) {
+      console.log("\n[guardian] 📱 WhatsApp pairing in progress. Please scan the QR code in the Control UI.");
+      hasShownWaitMessage = true;
+    }
+
+    console.log("[guardian] Waiting for pairing completion...");
+    const waitRes = await callRpc(ws, "web.login.wait", { timeoutMs: WAIT_TIMEOUT });
+    const result = waitRes.payload || waitRes.result;
+
+    if (result && (result.connected || (result.message && result.message.includes("515")))) {
+      console.log("[guardian] ✅ Pairing completed! Saving session and restarting gateway...");
+      hasShownWaitMessage = false;
+      
+      // Auto-reapply config to finalize pairing
+      const getRes = await callRpc(ws, "config.get", {});
+      if (getRes.ok) {
+        await callRpc(ws, "config.apply", { raw: getRes.payload.raw, baseHash: getRes.payload.hash });
+        console.log("[guardian] Configuration re-applied.");
+      }
+    }
+
+  } catch (e) {
+    // Normal timeout or gateway starting up
+  } finally {
+    isWaiting = false;
+    if (ws) ws.close();
+  }
+}
+
+console.log("[guardian] ⚔️ WhatsApp Guardian active. Monitoring pairing status...");
+setInterval(checkStatus, CHECK_INTERVAL);
+setTimeout(checkStatus, 10000);