feat: stabilize openclaw with rolling backups, blocking QR wait, and structured logging

scripts/entrypoint.sh

@@ -66,12 +66,22 @@ done
 
 echo "[entrypoint] Starting OpenClaw gateway on port 7860..."
 
-# 启动 WhatsApp 登录守护：仅循环调用 web.login.wait（不调用 web.login.start），
-# 这样当用户在 UI 点 Login 并扫码后，由本脚本处理 515 重启；UI 未调用 web.login.wait 时本脚本为唯一调用者，无竞态。
+
+# 启动 WhatsApp 登录守护：仅循环调用 web.login.wait
+# 这样当用户在 UI 点 Login 并扫码后，由本脚本处理 515 重启
 (
   sleep 25
   NODE_PATH=/app/openclaw/node_modules node /home/node/scripts/wa-login-guardian.cjs &
   echo "[entrypoint] WhatsApp login guardian started (PID $!)"
 ) &
 
+# ── 启动 QR Code Detection Manager (BLOCKING CHECK) ──
+# 必须在 gateway 启动之前或并行启动，监控日志中的 QR 码请求
+# 这里我们让它并行运行，监控文件系统和日志
+(
+  sleep 10
+  NODE_PATH=/app/openclaw/node_modules node /home/node/scripts/qr-detection-manager.cjs "${SPACE_HOST:-https://huggingface.co/spaces/tao-shen/openclaw-ai}" &
+  echo "[entrypoint] QR Detection Manager started (PID $!)"
+) &
+
 exec node openclaw.mjs gateway

scripts/logger.js

@@ -0,0 +1,64 @@
+/**
+ * Structured Logger for OpenClaw
+ * Provides consistent JSON logging for HF Spaces
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Ensure logs directory exists
+const LOG_DIR = path.join(process.env.HOME || '/home/node', 'logs');
+if (!fs.existsSync(LOG_DIR)) {
+    try {
+        fs.mkdirSync(LOG_DIR, { recursive: true });
+    } catch (e) {
+        // Ignore if we can't create it (might be read-only or race condition)
+    }
+}
+
+const LOG_FILE = path.join(LOG_DIR, 'app.json.log');
+
+class Logger {
+    constructor(moduleName) {
+        this.module = moduleName;
+    }
+
+    _log(level, message, data = {}) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: level.toUpperCase(),
+            module: this.module,
+            message,
+            ...data
+        };
+
+        const jsonLine = JSON.stringify(entry);
+        
+        // Write to stdout for HF Logs visibility
+        console.log(jsonLine);
+
+        // Also append to local file for persistence within container life
+        try {
+            fs.appendFileSync(LOG_FILE, jsonLine + '\n');
+        } catch (e) {
+            // Fallback if file write fails
+            console.error(`[LOGGER_FAIL] Could not write to log file: ${e.message}`);
+        }
+    }
+
+    info(message, data) { this._log('INFO', message, data); }
+    warn(message, data) { this._log('WARN', message, data); }
+    error(message, data) { this._log('ERROR', message, data); }
+    debug(message, data) { this._log('DEBUG', message, data); }
+    
+    // Special method for critical state changes
+    state(stateName, previousState, newState, data) {
+        this._log('STATE_CHANGE', `State changed: ${stateName}`, {
+            previousState,
+            newState,
+            ...data
+        });
+    }
+}
+
+module.exports = (moduleName) => new Logger(moduleName);

scripts/restore_from_dataset.py

@@ -2,7 +2,7 @@ import os
 import tarfile
 import sys
 
-from huggingface_hub import hf_hub_download
+from huggingface_hub import hf_hub_download, HfApi
 
 
 def main() -> None:
@@ -20,28 +20,51 @@ def main() -> None:
         # 未配置就直接跳过，不报错以免阻塞网关启动
         return
 
-    filename = "state/openclaw.tar"
-
     try:
-        tar_path = hf_hub_download(
-            repo_id=repo_id,
-            repo_type="dataset",
-            filename=filename,
-            token=token,
-        )
-    except Exception:
-        # 第一次运行或文件不存在时，直接跳过
-        return
+        # List all files and find the latest backup
+        api = HfApi(token=token)
+        files = api.list_repo_files(repo_id=repo_id, repo_type="dataset")
+        
+        # Filter for our backup pattern
+        backups = sorted([f for f in files if f.startswith("state/backup-") and f.endswith(".tar")], reverse=True)
+        
+        if not backups:
+            # Fallback to legacy filename if no rolling backups exist
+            if "state/openclaw.tar" in files:
+                backups = ["state/openclaw.tar"]
+            else:
+                print("[restore_from_dataset] No backups found.", file=sys.stderr)
+                return
 
-    state_dir = os.path.expanduser("~/.openclaw")
-    os.makedirs(state_dir, exist_ok=True)
+        # Try to restore from the latest backup, falling back to older ones if needed
+        success = False
+        for backup_file in backups:
+            print(f"[restore_from_dataset] Attempting to restore from: {backup_file}")
+            try:
+                tar_path = hf_hub_download(
+                    repo_id=repo_id,
+                    repo_type="dataset",
+                    filename=backup_file,
+                    token=token,
+                )
+                
+                with tarfile.open(tar_path, "r") as tf:
+                    tf.extractall(state_dir)
+                
+                print(f"[restore_from_dataset] Successfully restored from {backup_file}")
+                success = True
+                break
+            except Exception as e:
+                print(f"[restore_from_dataset] Failed to restore {backup_file}: {e}", file=sys.stderr)
+                # Continue to next backup
+        
+        if not success:
+             print("[restore_from_dataset] All backup restore attempts failed.", file=sys.stderr)
+             return
 
-    try:
-        with tarfile.open(tar_path, "r") as tf:
-            tf.extractall(state_dir)
     except Exception as e:
-        # 打印到 stderr，但不阻塞启动
-        print(f"[restore_from_dataset] Failed to extract {tar_path}: {e}", file=sys.stderr)
+        # General failure (network, auth, etc)
+        print(f"[restore_from_dataset] Restore process failed: {e}", file=sys.stderr)
         return
 
     # 重要：不要删除 credentials/whatsapp。恢复的凭证用于自动连接；

scripts/save_to_dataset.py

@@ -6,13 +6,23 @@ import sys
 from huggingface_hub import HfApi
 
 
+import os
+import tarfile
+import tempfile
+import sys
+import time
+from datetime import datetime
+
+from huggingface_hub import HfApi
+
 def main() -> None:
     """
-    将 ~/.openclaw 打包为 tar 并上传到 Hugging Face Dataset。
-
-    依赖环境变量：
-    - HF_TOKEN: 具有写入/读取权限的 HF Access Token
-    - OPENCLAW_DATASET_REPO: 数据集 repo_id，例如 "tao-shen/openclaw"
+    Backs up ~/.openclaw to Hugging Face Dataset with rolling history.
+    Keeps the last 5 backups to prevent data loss from corruption.
+    
+    Env vars:
+    - HF_TOKEN
+    - OPENCLAW_DATASET_REPO
     """
     repo_id = os.environ.get("OPENCLAW_DATASET_REPO")
     token = os.environ.get("HF_TOKEN")
@@ -20,33 +30,33 @@ def main() -> None:
     state_dir = os.path.expanduser("~/.openclaw")
 
     if not repo_id or not token:
+        print("[save_to_dataset] Missing configuration.", file=sys.stderr)
         return
 
     if not os.path.isdir(state_dir):
-        # 还没有任何状态可保存
+        print("[save_to_dataset] No state to save.", file=sys.stderr)
         return
 
-    # 若 WhatsApp 凭证目录不完整（例如 401 后仅剩 creds.json），不要上传覆盖 dataset，
-    # 否则会用坏状态覆盖之前的好状态，导致下次恢复后无法连接。
+    # 1. Validation: Ensure we have valid credentials before backing up
     wa_creds_dir = os.path.join(state_dir, "credentials", "whatsapp", "default")
     if os.path.isdir(wa_creds_dir):
         file_count = len([f for f in os.listdir(wa_creds_dir) if os.path.isfile(os.path.join(wa_creds_dir, f))])
-        if file_count < 10:
-            # Baileys 完整认证需要 creds.json + 大量 pre-key-*.json 等，少于 10 个文件视为不完整
-            print(
-                f"[save_to_dataset] Skip upload: WhatsApp credentials incomplete ({file_count} files). "
-                "Keeping previous dataset state.",
-                file=sys.stderr,
-            )
+        if file_count < 2:
+             # Basic sanity check: needs at least creds.json + keys. 
+             # Lowered from 10 to 2 to be less aggressive but still catch empty/broken states.
+            print(f"[save_to_dataset] Skip: WhatsApp credentials incomplete ({file_count} files).", file=sys.stderr)
             return
 
-    api = HfApi()
+    api = HfApi(token=token)
+    
+    # Generate timestamped filename
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = f"state/backup-{timestamp}.tar"
 
     with tempfile.TemporaryDirectory() as tmpdir:
         tar_path = os.path.join(tmpdir, "openclaw.tar")
 
         def exclude_filter(info: tarfile.TarInfo) -> tarfile.TarInfo | None:
-            # 排除 extensions symlink（它指向构建产物目录，无需持久化）
             if info.name in ("./extensions", "extensions"):
                 return None
             return info
@@ -55,20 +65,37 @@ def main() -> None:
             with tarfile.open(tar_path, "w") as tf:
                 tf.add(state_dir, arcname=".", filter=exclude_filter)
         except Exception as e:
-            print(f"[save_to_dataset] Failed to create tar from {state_dir}: {e}", file=sys.stderr)
+            print(f"[save_to_dataset] Failed to compress: {e}", file=sys.stderr)
             return
 
+        print(f"[save_to_dataset] Uploading backup: {filename}")
         try:
             api.upload_file(
                 path_or_fileobj=tar_path,
-                path_in_repo="state/openclaw.tar",
+                path_in_repo=filename,
                 repo_id=repo_id,
                 repo_type="dataset",
-                token=token,
             )
         except Exception as e:
-            print(f"[save_to_dataset] Failed to upload {tar_path} to {repo_id}: {e}", file=sys.stderr)
+            print(f"[save_to_dataset] Upload failed: {e}", file=sys.stderr)
+            return
 
+    # 2. Rotation: Delete old backups, keep last 5
+    try:
+        files = api.list_repo_files(repo_id=repo_id, repo_type="dataset")
+        backups = sorted([f for f in files if f.startswith("state/backup-") and f.endswith(".tar")])
+        
+        if len(backups) > 5:
+            # Delete oldest
+            to_delete = backups[:-5]
+            print(f"[save_to_dataset] Rotating backups, deleting: {to_delete}")
+            for old_backup in to_delete:
+                api.delete_file(
+                    path_in_repo=old_backup,
+                    repo_id=repo_id,
+                    repo_type="dataset",
+                    token=token
+                )
+    except Exception as e:
+        print(f"[save_to_dataset] Rotation failed (non-fatal): {e}", file=sys.stderr)
 
-if __name__ == "__main__":
-    main()