feat: implement persistent WhatsApp credential syncing and automatic session recovery in guardian and health-server

README.md

@@ -44,12 +44,12 @@ license: mit
 - 🔌 **Any LLM:** Use Claude, OpenAI GPT, Google Gemini, Grok, DeepSeek, Qwen, and 40+ providers (set `LLM_API_KEY` and `LLM_MODEL` accordingly).
 - ⚡ **Zero Config:** Duplicate this Space and set **just three** secrets (LLM_API_KEY, LLM_MODEL, GATEWAY_TOKEN) – no other setup needed.
 - 🐳 **Fast Builds:** Uses a pre-built OpenClaw Docker image to deploy in minutes.
-- 💾 **Workspace Backup:** Chats and settings sync to a private HF Dataset via the `huggingface_hub` (Git fallback), preserving data automatically.
+- 💾 **Workspace Backup:** Chats, settings, and WhatsApp session state sync to a private HF Dataset via the `huggingface_hub` (Git fallback), preserving data automatically.
 - 💓 **Always-On:** Built-in keep-alive pings prevent the HF Space from sleeping, so the assistant is always online.
 - 👥 **Multi-User Messaging:** Support for Telegram (multi-user) and WhatsApp (pairing).
 - 📊 **Visual Dashboard:** Beautiful Web UI to monitor uptime, sync status, and active models.
 - 🔔 **Webhooks:** Get notified on restarts or backup failures via standard webhooks.
-- 🔐 **Flexible Auth:** Secure the Control UI with either a gateway token or password.
+- 🔐 **Flexible Auth:** Secure the Control UI with either a gateway token or password, with automatic token redirect for the web UI.
 - 🏠 **100% HF-Native:** Runs entirely on HuggingFace’s free infrastructure (2 vCPU, 16GB RAM).
 
 ## 🎥 Video Tutorial
@@ -102,6 +102,8 @@ To use WhatsApp:
 2. In the Control UI, go to **Channels** → **WhatsApp** → **Login**.
 3. Scan the QR code with your phone. 📱
 
+The Control UI now redirects to `/?token=...` automatically, so you usually won't need to paste `GATEWAY_TOKEN` manually in the browser.
+
 ## 💾 Workspace Backup *(Optional)*
 
 For persistent chat history and configuration:
@@ -109,7 +111,7 @@ For persistent chat history and configuration:
 - Set `HF_USERNAME` to your HuggingFace username.
 - Set `HF_TOKEN` to a HuggingFace token with write access.
 
-Optionally set `BACKUP_DATASET_NAME` (default: `huggingclaw-backup`) to choose the HF Dataset name. On first run, HuggingClaw will create (or use) the private Dataset repo `HF_USERNAME/SPACE-backup`, then restore your workspace on startup and sync changes every 10 minutes. The workspace is also saved on graceful shutdown. This ensures your data survives restarts.
+Optionally set `BACKUP_DATASET_NAME` (default: `huggingclaw-backup`) to choose the HF Dataset name. On first run, HuggingClaw will create (or use) the private Dataset repo `HF_USERNAME/SPACE-backup`, then restore your workspace on startup and sync changes every 10 minutes. The workspace is also saved on graceful shutdown. If you use WhatsApp, HuggingClaw also stores a hidden backup of the WhatsApp session credentials so paired logins can survive restarts.
 
 ## 📊 Dashboard & Monitoring
 
@@ -289,7 +291,8 @@ HuggingClaw keeps the Space awake without external cron tools:
 - **Backup restore failing:** Make sure `HF_USERNAME` and `HF_TOKEN` are correct (token needs write access to your Dataset).
 - **Space keeps sleeping:** Check logs for `Keep-alive` messages. Ensure `KEEP_ALIVE_INTERVAL` isn’t set to `0`.
 - **Auth errors / proxy:** If you see reverse-proxy auth errors, add the logged IPs under `TRUSTED_PROXIES` (from logs `remote=x.x.x.x`).
-- **Control UI says too many failed authentication attempts:** Wait for the retry window to expire, then open the Space in an incognito window or clear site storage for your Space before entering the current `GATEWAY_TOKEN` again.
+- **Control UI says too many failed authentication attempts:** Wait for the retry window to expire, then open the Space in an incognito window or clear site storage for your Space. The root UI now auto-injects the current `GATEWAY_TOKEN`, so a fresh browser session usually fixes stale-token lockouts.
+- **WhatsApp lost its session after restart:** Make sure `HF_USERNAME` and `HF_TOKEN` are configured so the hidden session backup can be restored on boot.
 - **UI blocked (CORS):** Set `ALLOWED_ORIGINS=https://your-space-name.hf.space`.
 - **Version mismatches:** Pin a specific OpenClaw build with the `OPENCLAW_VERSION` Variable in HF Spaces, or `--build-arg OPENCLAW_VERSION=...` locally.
 

health-server.js

@@ -21,11 +21,11 @@ let gatewayStatusCache = {
   },
 };
 
-function getPathname(url) {
+function parseRequestUrl(url) {
   try {
-    return new URL(url, "http://localhost").pathname;
+    return new URL(url, "http://localhost");
   } catch {
-    return "/";
+    return new URL("http://localhost/");
   }
 }
 
@@ -33,11 +33,16 @@ function isDashboardRoute(pathname) {
   return pathname === "/dashboard" || pathname === "/dashboard/";
 }
 
+function isControlRoute(pathname) {
+  return pathname === "/control" || pathname === "/control/";
+}
+
 function isLocalRoute(pathname) {
   return (
     pathname === "/health" ||
     pathname === "/status" ||
-    isDashboardRoute(pathname)
+    isDashboardRoute(pathname) ||
+    isControlRoute(pathname)
   );
 }
 
@@ -382,7 +387,7 @@ function renderDashboard() {
                 <span class="stat-label">Telegram</span>
                 <span id="tg-status">Loading...</span>
             </div>
-            <a href="/" class="stat-btn">Open Control UI</a>
+            <a href="/control" class="stat-btn">Open Control UI</a>
         </div>
 
         <div class="stat-card" style="width: 100%;">
@@ -545,7 +550,8 @@ function proxyUpgrade(req, socket, head) {
 }
 
 const server = http.createServer((req, res) => {
-  const pathname = getPathname(req.url || "/");
+  const parsedUrl = parseRequestUrl(req.url || "/");
+  const pathname = parsedUrl.pathname;
   const uptime = Math.floor((Date.now() - startTime) / 1000);
   const uptimeHuman = `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m`;
 
@@ -585,11 +591,20 @@ const server = http.createServer((req, res) => {
     return;
   }
 
+  if ((pathname === "/" || isControlRoute(pathname)) && req.method === "GET" && !parsedUrl.searchParams.get("token") && GATEWAY_TOKEN) {
+    res.writeHead(302, {
+      Location: `/?token=${encodeURIComponent(GATEWAY_TOKEN)}`,
+      "Cache-Control": "no-store",
+    });
+    res.end();
+    return;
+  }
+
   proxyHttp(req, res);
 });
 
 server.on("upgrade", (req, socket, head) => {
-  const pathname = getPathname(req.url || "/");
+  const pathname = parseRequestUrl(req.url || "/").pathname;
   if (isLocalRoute(pathname)) {
     socket.destroy();
     return;

start.sh

@@ -163,6 +163,23 @@ if [ -n "$HF_USERNAME" ] && [ -n "$HF_TOKEN" ]; then
   cd /
 fi
 
+# ── Restore persisted WhatsApp credentials (if present) ──
+WA_BACKUP_DIR="/home/node/.openclaw/workspace/.huggingclaw-state/credentials/whatsapp/default"
+WA_CREDS_DIR="/home/node/.openclaw/credentials/whatsapp/default"
+if [ -d "$WA_BACKUP_DIR" ]; then
+  WA_FILE_COUNT=$(find "$WA_BACKUP_DIR" -type f | wc -l | tr -d ' ')
+  if [ "$WA_FILE_COUNT" -ge 2 ]; then
+    echo "📱 Restoring WhatsApp credentials..."
+    rm -rf "$WA_CREDS_DIR"
+    mkdir -p "$(dirname "$WA_CREDS_DIR")"
+    cp -R "$WA_BACKUP_DIR" "$WA_CREDS_DIR"
+    chmod -R go-rwx /home/node/.openclaw/credentials/whatsapp 2>/dev/null || true
+    echo "  ✅ WhatsApp credentials restored"
+  else
+    echo "  ⚠️  Saved WhatsApp credentials look incomplete (${WA_FILE_COUNT} files), skipping restore."
+  fi
+fi
+
 # ── Build config ──
 CONFIG_JSON=$(cat <<'CONFIGEOF'
 {
@@ -243,8 +260,8 @@ CONFIG_JSON=$(echo "$CONFIG_JSON" | jq '.channels.whatsapp = {"dmPolicy": "pairi
 echo "$CONFIG_JSON" > "/home/node/.openclaw/openclaw.json"
 chmod 600 /home/node/.openclaw/openclaw.json
 
-# ── Enable Iframe Fix (Security: No Token Redirect) ──
-# This Node.js preload script strips X-Frame-Options to allow HF Space embedding
+# ── Enable Gateway Preload Fixes ──
+# This preload script keeps iframe embedding working on HF Spaces.
 export NODE_OPTIONS="${NODE_OPTIONS:+$NODE_OPTIONS }--require /home/node/app/iframe-fix.cjs"
 
 # ── Startup Summary ──

wa-guardian.js

@@ -7,6 +7,8 @@
  */
 "use strict";
 
+const fs = require("fs");
+const path = require("path");
 const { WebSocket } = require('/home/node/.openclaw/openclaw-app/node_modules/ws');
 const { randomUUID } = require('node:crypto');
 
@@ -15,11 +17,19 @@ const GATEWAY_TOKEN = process.env.GATEWAY_TOKEN || "huggingclaw";
 const CHECK_INTERVAL = 5000;
 const WAIT_TIMEOUT = 120000;
 const AUTH_FAILURE_COOLDOWN = 5 * 60 * 1000;
+const POST_515_NO_LOGOUT_MS = 90 * 1000;
+const RESET_MARKER_PATH = path.join(
+  process.env.HOME || "/home/node",
+  ".openclaw",
+  "workspace",
+  ".reset_credentials",
+);
 
 let isWaiting = false;
 let hasShownWaitMessage = false;
 let authFailureUntil = 0;
 let authFailureLogged = false;
+let last515At = 0;
 
 function extractErrorMessage(msg) {
   if (!msg || typeof msg !== "object") return "Unknown error";
@@ -29,6 +39,16 @@ function extractErrorMessage(msg) {
   return "Unknown error";
 }
 
+function writeResetMarker() {
+  try {
+    fs.mkdirSync(path.dirname(RESET_MARKER_PATH), { recursive: true });
+    fs.writeFileSync(RESET_MARKER_PATH, "reset\n");
+    console.log(`[guardian] Created backup reset marker at ${RESET_MARKER_PATH}`);
+  } catch (error) {
+    console.log(`[guardian] Failed to write backup reset marker: ${error.message}`);
+  }
+}
+
 async function createConnection() {
   return new Promise((resolve, reject) => {
     const ws = new WebSocket(GATEWAY_URL);
@@ -76,6 +96,10 @@ async function callRpc(ws, method, params) {
       const msg = JSON.parse(data.toString());
       if (msg.id === id) {
         ws.removeListener("message", handler);
+        if (msg.ok === false) {
+          reject(new Error(extractErrorMessage(msg)));
+          return;
+        }
         resolve(msg);
       }
     };
@@ -105,8 +129,34 @@ async function checkStatus() {
       return;
     }
 
+    const lastError = String(wa.lastError || "").toLowerCase();
+    const recentlySaw515 = Date.now() - last515At < POST_515_NO_LOGOUT_MS;
+    const needsLogout = wa.linked && !wa.connected && !recentlySaw515 &&
+      (
+        lastError.includes("401") ||
+        lastError.includes("unauthorized") ||
+        lastError.includes("logged out") ||
+        lastError.includes("440") ||
+        lastError.includes("conflict")
+      );
+
+    if (needsLogout) {
+      console.log("[guardian] Clearing invalid WhatsApp session so a fresh QR can be used...");
+      try {
+        await callRpc(ws, "channels.logout", { channel: "whatsapp" });
+        writeResetMarker();
+        hasShownWaitMessage = false;
+        console.log("[guardian] Logged out invalid WhatsApp session.");
+      } catch (error) {
+        console.log(`[guardian] Failed to log out invalid session: ${error.message}`);
+      }
+      ws.close();
+      return;
+    }
+
     // If connected, we are good
     if (wa.connected) {
+      hasShownWaitMessage = false;
       ws.close();
       return;
     }
@@ -121,17 +171,29 @@ async function checkStatus() {
     console.log("[guardian] Waiting for pairing completion...");
     const waitRes = await callRpc(ws, "web.login.wait", { timeoutMs: WAIT_TIMEOUT });
     const result = waitRes.payload || waitRes.result;
+    const message = result?.message || "";
+    const linkedAfter515 = !result?.connected && message.includes("515");
+
+    if (linkedAfter515) {
+      last515At = Date.now();
+    }
 
-    if (result && (result.connected || (result.message && result.message.includes("515")))) {
-      console.log("[guardian] ✅ Pairing completed! Saving session and restarting gateway...");
+    if (result && (result.connected || linkedAfter515)) {
       hasShownWaitMessage = false;
-      
-      // Auto-reapply config to finalize pairing
+
+      if (linkedAfter515) {
+        console.log("[guardian] 515 after scan: credentials saved, reloading config to start WhatsApp...");
+      } else {
+        console.log("[guardian] ✅ Pairing completed! Reloading config...");
+      }
+
       const getRes = await callRpc(ws, "config.get", {});
-      if (getRes.ok) {
+      if (getRes.payload?.raw && getRes.payload?.hash) {
         await callRpc(ws, "config.apply", { raw: getRes.payload.raw, baseHash: getRes.payload.hash });
         console.log("[guardian] Configuration re-applied.");
       }
+    } else if (!message.includes("No active") && !message.includes("Still waiting")) {
+      console.log(`[guardian] Wait result: ${message}`);
     }
 
   } catch (e) {

workspace-sync.py

@@ -11,10 +11,15 @@ import os
 import sys
 import time
 import signal
+import shutil
 import subprocess
 from pathlib import Path
 
 WORKSPACE = Path("/home/node/.openclaw/workspace")
+STATE_DIR = WORKSPACE / ".huggingclaw-state"
+WHATSAPP_CREDS_DIR = Path("/home/node/.openclaw/credentials/whatsapp/default")
+WHATSAPP_BACKUP_DIR = STATE_DIR / "credentials" / "whatsapp" / "default"
+RESET_MARKER = WORKSPACE / ".reset_credentials"
 INTERVAL = int(os.environ.get("SYNC_INTERVAL", "600"))
 HF_TOKEN = os.environ.get("HF_TOKEN", "")
 HF_USERNAME = os.environ.get("HF_USERNAME", "")
@@ -31,6 +36,47 @@ signal.signal(signal.SIGTERM, signal_handler)
 signal.signal(signal.SIGINT, signal_handler)
 
 
+def count_files(path: Path) -> int:
+    """Count regular files recursively under a path."""
+    if not path.exists():
+        return 0
+    return sum(1 for child in path.rglob("*") if child.is_file())
+
+
+def snapshot_state_into_workspace() -> None:
+    """
+    Mirror persistent state into the workspace-backed dataset repo.
+
+    This keeps WhatsApp credentials in a hidden folder that is synced together
+    with the workspace, without changing the live credentials location.
+    """
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+
+        if RESET_MARKER.exists():
+            if WHATSAPP_BACKUP_DIR.exists():
+                shutil.rmtree(WHATSAPP_BACKUP_DIR, ignore_errors=True)
+                print("🧹 Removed backed-up WhatsApp credentials after reset request.")
+            RESET_MARKER.unlink(missing_ok=True)
+            return
+
+        if not WHATSAPP_CREDS_DIR.exists():
+            return
+
+        file_count = count_files(WHATSAPP_CREDS_DIR)
+        if file_count < 2:
+            if file_count > 0:
+                print(f"📦 WhatsApp backup skipped: credentials incomplete ({file_count} files).")
+            return
+
+        WHATSAPP_BACKUP_DIR.parent.mkdir(parents=True, exist_ok=True)
+        if WHATSAPP_BACKUP_DIR.exists():
+            shutil.rmtree(WHATSAPP_BACKUP_DIR, ignore_errors=True)
+        shutil.copytree(WHATSAPP_CREDS_DIR, WHATSAPP_BACKUP_DIR)
+    except Exception as e:
+        print(f"  ⚠️ Could not snapshot WhatsApp state: {e}")
+
+
 def has_changes():
     """Check if workspace has uncommitted changes (git-based check)."""
     try:
@@ -142,6 +188,8 @@ def main():
 
     use_hf_hub = bool(HF_TOKEN and HF_USERNAME)
 
+    snapshot_state_into_workspace()
+
     if use_hf_hub:
         print(f"🔄 Workspace sync started (huggingface_hub): every {INTERVAL}s → {HF_USERNAME}/{BACKUP_DATASET}")
     else:
@@ -156,6 +204,8 @@ def main():
         if not running:
             break
 
+        snapshot_state_into_workspace()
+
         if not has_changes():
             continue