refactor: modularize workspace sync logic and optimize state snapshotting with reduced sync interval

.env.example

@@ -162,8 +162,8 @@ WORKSPACE_GIT_NAME=OpenClaw Bot
 # Keep-alive ping interval (seconds). Default: 300. Set 0 to disable.
 KEEP_ALIVE_INTERVAL=300
 
-# Workspace auto-sync interval (seconds). Default: 600.
-SYNC_INTERVAL=600
+# Workspace auto-sync interval (seconds). Default: 180.
+SYNC_INTERVAL=180
 
 # Webhooks: Standard POST notifications for lifecycle events
 # WEBHOOK_URL=https://your-webhook-endpoint.com/log

Dockerfile

@@ -19,6 +19,27 @@ RUN apt-get update && apt-get install -y \
     curl \
     python3 \
     python3-pip \
+    chromium \
+    libnss3 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libdrm2 \
+    libgbm1 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxrandr2 \
+    libxkbcommon0 \
+    libx11-6 \
+    libxext6 \
+    libxfixes3 \
+    libasound2 \
+    fonts-dejavu-core \
+    fonts-liberation \
+    fonts-noto-color-emoji \
+    fonts-freefont-ttf \
+    fonts-ipafont-gothic \
+    fonts-wqy-zenhei \
+    xfonts-scalable \
     --no-install-recommends && \
     pip3 install --no-cache-dir --break-system-packages huggingface_hub && \
     rm -rf /var/lib/apt/lists/*
@@ -30,6 +51,13 @@ RUN mkdir -p /home/node/app /home/node/.openclaw && \
 # Copy pre-built OpenClaw (skips npm install entirely — much faster!)
 COPY --from=openclaw --chown=1000:1000 /app /home/node/.openclaw/openclaw-app
 
+# Add Playwright in an isolated sidecar node_modules so we do not mutate the
+# bundled OpenClaw app dependency tree.
+RUN mkdir -p /home/node/browser-deps && \
+    cd /home/node/browser-deps && \
+    npm init -y && \
+    PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install --omit=dev playwright@1.59.1
+
 # Symlink openclaw CLI so it's available globally
 RUN ln -s /home/node/.openclaw/openclaw-app/openclaw.mjs /usr/local/bin/openclaw 2>/dev/null || \
     npm install -g openclaw@${OPENCLAW_VERSION}
@@ -48,6 +76,7 @@ USER node
 ENV HOME=/home/node \
     OPENCLAW_VERSION=${OPENCLAW_VERSION} \
     PATH=/home/node/.local/bin:/usr/local/bin:$PATH \
+    NODE_PATH=/home/node/browser-deps/node_modules \
     NODE_OPTIONS="--require /opt/dns-fix.js"
 
 WORKDIR /home/node/app

README.md

@@ -42,6 +42,7 @@ 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.
+- 🌐 **Built-In Browser:** Headless Chromium is included in the Space, so browser actions work from the start.
 - 💾 **Workspace Backup:** Chats, settings, and WhatsApp session state sync to a private HF Dataset via the `huggingface_hub` (Git fallback), preserving data automatically.
 - ⏰ **External Keep-Alive:** Set up a one-time UptimeRobot monitor from the dashboard to help keep free HF Spaces awake.
 - 👥 **Multi-User Messaging:** Support for Telegram (multi-user) and WhatsApp (pairing).
@@ -60,7 +61,7 @@ Watch a quick walkthrough on YouTube: [Deploying HuggingClaw on HF Spaces](https
 
 [![Duplicate this Space](https://huggingface.co/datasets/huggingface/badges/resolve/main/duplicate-this-space-xl.svg)](https://huggingface.co/spaces/somratpro/HuggingClaw?duplicate=true)
 
-Click the button above to duplicate the template. 
+Click the button above to duplicate the template.
 
 ### Step 2: Add Your Secrets
 
@@ -119,7 +120,7 @@ For persistent chat history and configuration, HuggingClaw can sync your workspa
 | `HF_USERNAME` | — | Your HuggingFace username |
 | `HF_TOKEN` | — | HF token with write access |
 | `BACKUP_DATASET_NAME` | `huggingclaw-backup` | Dataset name for backup repo |
-| `SYNC_INTERVAL` | `600` | Sync interval in seconds |
+| `SYNC_INTERVAL` | `180` | Sync interval in seconds |
 | `WORKSPACE_GIT_USER` | `openclaw@example.com` | Git commit email for syncs |
 | `WORKSPACE_GIT_NAME` | `OpenClaw Bot` | Git commit name for syncs |
 

health-server.js

@@ -196,8 +196,7 @@ async function resolveSpaceIsPrivate(parsedUrl) {
     const statusCode = await fetchStatusCode(
       `https://huggingface.co/api/spaces/${ref.owner}/${ref.repo}`,
     );
-    const isPrivate =
-      statusCode === 401 || statusCode === 403 || statusCode === 404;
+    const isPrivate = statusCode === 401 || statusCode === 403 || statusCode === 404;
     spaceVisibilityCache.set(cacheKey, { isPrivate, timestamp: Date.now() });
     return isPrivate;
   } catch {

start.sh

@@ -9,6 +9,7 @@ set -e
 OPENCLAW_VERSION="${OPENCLAW_VERSION:-latest}"
 WHATSAPP_ENABLED="${WHATSAPP_ENABLED:-false}"
 WHATSAPP_ENABLED_NORMALIZED=$(printf '%s' "$WHATSAPP_ENABLED" | tr '[:upper:]' '[:lower:]')
+SYNC_INTERVAL="${SYNC_INTERVAL:-180}"
 echo ""
 echo "  ╔══════════════════════════════════════════╗"
 echo "  ║          🦞 HuggingClaw Gateway          ║"
@@ -91,6 +92,8 @@ esac
 # ── Setup directories ──
 mkdir -p /home/node/.openclaw/agents/main/sessions
 mkdir -p /home/node/.openclaw/credentials
+mkdir -p /home/node/.openclaw/memory
+mkdir -p /home/node/.openclaw/extensions
 mkdir -p /home/node/.openclaw/workspace
 chmod 700 /home/node/.openclaw
 chmod 700 /home/node/.openclaw/credentials
@@ -165,6 +168,22 @@ if [ -n "$HF_USERNAME" ] && [ -n "$HF_TOKEN" ]; then
   cd /
 fi
 
+# ── Restore persisted OpenClaw state (if present) ──
+STATE_BACKUP_ROOT="/home/node/.openclaw/workspace/.huggingclaw-state/openclaw"
+if [ -d "$STATE_BACKUP_ROOT" ]; then
+  echo "🧠 Restoring OpenClaw state..."
+  for source_path in "$STATE_BACKUP_ROOT"/*; do
+    [ -e "$source_path" ] || continue
+    name="$(basename "$source_path")"
+    target_path="/home/node/.openclaw/${name}"
+
+    rm -rf "$target_path"
+    mkdir -p "$(dirname "$target_path")"
+    cp -R "$source_path" "$target_path"
+  done
+  echo "  ✅ OpenClaw state restored"
+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"
@@ -212,6 +231,31 @@ CONFIG_JSON=$(echo "$CONFIG_JSON" | jq ".gateway.auth.token = \"$GATEWAY_TOKEN\"
 # Model configuration at top level
 CONFIG_JSON=$(echo "$CONFIG_JSON" | jq ".agents.defaults.model = \"$LLM_MODEL\"")
 
+# Browser configuration (managed local Chromium in HF/Docker)
+BROWSER_EXECUTABLE_PATH=""
+for candidate in /usr/bin/chromium /usr/bin/chromium-browser /snap/bin/chromium; do
+  if [ -x "$candidate" ]; then
+    BROWSER_EXECUTABLE_PATH="$candidate"
+    break
+  fi
+done
+
+BROWSER_SHOULD_ENABLE=false
+if [ -n "$BROWSER_EXECUTABLE_PATH" ] && [ -x "$BROWSER_EXECUTABLE_PATH" ]; then
+  BROWSER_SHOULD_ENABLE=true
+fi
+
+if [ "$BROWSER_SHOULD_ENABLE" = "true" ]; then
+  CONFIG_JSON=$(echo "$CONFIG_JSON" | jq \
+    ".browser = {
+      \"enabled\": true,
+      \"defaultProfile\": \"openclaw\",
+      \"headless\": true,
+      \"noSandbox\": true,
+      \"executablePath\": \"$BROWSER_EXECUTABLE_PATH\"
+    } | .agents.defaults.sandbox.browser.allowHostControl = true")
+fi
+
 # Control UI origin (allow HF Space URL for web UI access)
 if [ -n "$SPACE_HOST" ]; then
   CONFIG_JSON=$(echo "$CONFIG_JSON" | jq ".gateway.controlUi.allowedOrigins = [\"https://${SPACE_HOST}\"]")
@@ -321,6 +365,11 @@ printf "  │  %-40s │\n" "WhatsApp: ✅ enabled"
 else
 printf "  │  %-40s │\n" "WhatsApp: ❌ disabled"
 fi
+if [ "$BROWSER_SHOULD_ENABLE" = "true" ]; then
+printf "  │  %-40s │\n" "Browser: ✅ ${BROWSER_EXECUTABLE_PATH}"
+else
+printf "  │  %-40s │\n" "Browser: ❌ unavailable"
+fi
 if [ -n "$HF_USERNAME" ] && [ -n "$HF_TOKEN" ]; then
 printf "  │  %-40s │\n" "Backup: ✅ ${HF_USERNAME}/${BACKUP_DATASET:-huggingclaw-backup}"
 else
@@ -337,7 +386,7 @@ printf "  │  %-40s │\n" "Dashboard: https://${SPACE_HOST}"
 fi
 SYNC_STATUS="❌ disabled"
 if [ -n "$HF_USERNAME" ] && [ -n "$HF_TOKEN" ]; then
-  SYNC_STATUS="✅ every ${SYNC_INTERVAL:-600}s"
+  SYNC_STATUS="✅ every ${SYNC_INTERVAL:-180}s"
 fi
 printf "  │  %-40s │\n" "Auto-sync: $SYNC_STATUS"
 if [ -n "$WEBHOOK_URL" ]; then
@@ -358,19 +407,11 @@ fi
 graceful_shutdown() {
   echo ""
   echo "🛑 Shutting down gracefully..."
-  
-  # Commit any unsaved workspace changes
-  if [ -d "/home/node/.openclaw/workspace/.git" ]; then
-    echo "💾 Saving workspace before exit..."
-    cd /home/node/.openclaw/workspace
-    git add -A 2>/dev/null
-    if ! git diff --cached --quiet 2>/dev/null; then
-      TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-      git commit -m "Shutdown sync ${TIMESTAMP}" 2>/dev/null
-      git push origin main 2>/dev/null && echo "  ✅ Workspace saved!" || echo "  ⚠️ Push failed"
-    else
-      echo "  ✅ No unsaved changes"
-    fi
+
+  if [ -f "/home/node/app/workspace-sync.py" ]; then
+    echo "💾 Saving OpenClaw state before exit..."
+    python3 /home/node/app/workspace-sync.py --sync-once || \
+      echo "  ⚠️ Could not complete shutdown sync"
   fi
   
   # Kill background processes
@@ -380,6 +421,26 @@ graceful_shutdown() {
 }
 trap graceful_shutdown SIGTERM SIGINT
 
+warmup_browser() {
+  [ "$BROWSER_SHOULD_ENABLE" = "true" ] || return 0
+
+  (
+    sleep 5
+
+    local attempt
+    for attempt in 1 2 3 4 5; do
+      if openclaw browser --browser-profile openclaw start >/dev/null 2>&1; then
+        openclaw browser --browser-profile openclaw open about:blank >/dev/null 2>&1 || true
+        echo "  ✅ Managed browser ready"
+        return 0
+      fi
+      sleep 2
+    done
+
+    echo "  ⚠️ Managed browser warm-up did not complete; first browser action may need a retry"
+  ) &
+}
+
 # ── Start background services ──
 export LLM_MODEL="$LLM_MODEL"
 # 10. Start Health Server & Dashboard
@@ -416,6 +477,9 @@ if [ "$WHATSAPP_ENABLED_NORMALIZED" = "true" ]; then
   echo "🛡️ WhatsApp Guardian started (PID: $GUARDIAN_PID)"
 fi
 
+# 11.5 Warm up the managed browser so first browser actions have a live tab
+warmup_browser
+
 # 12. Start Workspace Sync after startup settles
 python3 -u /home/node/app/workspace-sync.py &
 

workspace-sync.py

@@ -15,12 +15,20 @@ import shutil
 import subprocess
 from pathlib import Path
 
-WORKSPACE = Path("/home/node/.openclaw/workspace")
+OPENCLAW_HOME = Path("/home/node/.openclaw")
+WORKSPACE = OPENCLAW_HOME / "workspace"
 STATE_DIR = WORKSPACE / ".huggingclaw-state"
+OPENCLAW_STATE_BACKUP_DIR = STATE_DIR / "openclaw"
+EXCLUDED_STATE_NAMES = {
+    "workspace",
+    "openclaw-app",
+    "gateway.log",
+    "browser",
+}
 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"))
+INTERVAL = int(os.environ.get("SYNC_INTERVAL", "180"))
 INITIAL_DELAY = int(os.environ.get("SYNC_START_DELAY", "10"))
 HF_TOKEN = os.environ.get("HF_TOKEN", "")
 HF_USERNAME = os.environ.get("HF_USERNAME", "")
@@ -52,6 +60,24 @@ def snapshot_state_into_workspace() -> None:
     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 OPENCLAW_STATE_BACKUP_DIR.exists():
+            shutil.rmtree(OPENCLAW_STATE_BACKUP_DIR, ignore_errors=True)
+        OPENCLAW_STATE_BACKUP_DIR.mkdir(parents=True, exist_ok=True)
+
+        for source_path in OPENCLAW_HOME.iterdir():
+            if source_path.name in EXCLUDED_STATE_NAMES:
+                continue
+
+            backup_path = OPENCLAW_STATE_BACKUP_DIR / source_path.name
+            if source_path.is_dir():
+                shutil.copytree(source_path, backup_path)
+            elif source_path.is_file():
+                shutil.copy2(source_path, backup_path)
+    except Exception as e:
+        print(f"  ⚠️ Could not snapshot OpenClaw state: {e}")
+
     try:
         if not WHATSAPP_ENABLED:
             return
@@ -183,7 +209,94 @@ def sync_with_git():
         return False
 
 
+def run_sync_pass(use_hf_hub: bool) -> None:
+    """Snapshot state and push it if anything changed."""
+    snapshot_state_into_workspace()
+
+    if not has_changes():
+        return
+
+    ts = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    write_sync_status("syncing", f"Starting sync at {ts}")
+
+    if use_hf_hub:
+        if sync_with_hf_hub():
+            print(f"🔄 Workspace sync (hf_hub): pushed changes ({ts})")
+            write_sync_status("success", "Successfully pushed to HF Hub")
+            return
+
+        if sync_with_git():
+            print(f"🔄 Workspace sync (git fallback): pushed changes ({ts})")
+            write_sync_status("success", "Successfully pushed via git fallback")
+            return
+
+        msg = f"Workspace sync: failed ({ts}), will retry"
+        print(f"🔄 {msg}")
+        write_sync_status("error", msg)
+        trigger_webhook("sync", "error", msg)
+        return
+
+    if sync_with_git():
+        print(f"🔄 Workspace sync (git): pushed changes ({ts})")
+        write_sync_status("success", "Successfully pushed via git")
+        return
+
+    msg = f"Workspace sync: push failed ({ts}), will retry"
+    print(f"🔄 {msg}")
+    write_sync_status("error", msg)
+    trigger_webhook("sync", "error", msg)
+
+
 def main():
+    if "--snapshot-once" in sys.argv:
+        snapshot_state_into_workspace()
+        write_sync_status("configured", "State snapshot refreshed during shutdown.")
+        return
+
+    if "--sync-once" in sys.argv:
+        if not WORKSPACE.exists():
+            print("📁 Workspace sync: workspace not found, exiting.")
+            return
+
+        use_hf_hub = bool(HF_TOKEN and HF_USERNAME)
+        git_dir = WORKSPACE / ".git"
+
+        if not use_hf_hub and not git_dir.exists():
+            print("📁 Workspace sync: no git repo and no HF credentials, skipping.")
+            return
+
+        snapshot_state_into_workspace()
+
+        if not has_changes():
+            print("📁 Workspace sync: no changes to persist.")
+            write_sync_status("configured", "No new state changes to sync.")
+            return
+
+        ts = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        write_sync_status("syncing", f"Shutdown sync started at {ts}")
+
+        if use_hf_hub:
+            if sync_with_hf_hub():
+                print(f"🔄 Workspace sync (hf_hub): pushed changes ({ts})")
+                write_sync_status("success", "Shutdown sync pushed to HF Hub")
+                return
+            if sync_with_git():
+                print(f"🔄 Workspace sync (git fallback): pushed changes ({ts})")
+                write_sync_status("success", "Shutdown sync pushed via git fallback")
+                return
+            write_sync_status("error", "Shutdown sync failed")
+            print("📁 Workspace sync: shutdown sync failed.")
+            return
+
+        if sync_with_git():
+            print(f"🔄 Workspace sync (git): pushed changes ({ts})")
+            write_sync_status("success", "Shutdown sync pushed via git")
+            return
+
+        write_sync_status("error", "Shutdown sync failed")
+        print("📁 Workspace sync: shutdown sync failed.")
+        return
+
     if not WORKSPACE.exists():
         print("📁 Workspace sync: workspace not found, exiting.")
         return
@@ -204,50 +317,19 @@ def main():
     # Give the gateway a short head start before the first sync probe.
     time.sleep(INITIAL_DELAY)
 
-    snapshot_state_into_workspace()
-
     if use_hf_hub:
         print(f"🔄 Workspace sync started (huggingface_hub): every {INTERVAL}s → {HF_USERNAME}/{BACKUP_DATASET}")
     else:
         print(f"🔄 Workspace sync started (git): every {INTERVAL}s")
 
+    run_sync_pass(use_hf_hub)
+
     while running:
         time.sleep(INTERVAL)
         if not running:
             break
 
-        snapshot_state_into_workspace()
-
-        if not has_changes():
-            continue
-
-        ts = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
-        
-        write_sync_status("syncing", f"Starting sync at {ts}")
-
-        if use_hf_hub:
-            if sync_with_hf_hub():
-                print(f"🔄 Workspace sync (hf_hub): pushed changes ({ts})")
-                write_sync_status("success", "Successfully pushed to HF Hub")
-            else:
-                # Fallback to git
-                if sync_with_git():
-                    print(f"🔄 Workspace sync (git fallback): pushed changes ({ts})")
-                    write_sync_status("success", "Successfully pushed via git fallback")
-                else:
-                    msg = f"Workspace sync: failed ({ts}), will retry"
-                    print(f"🔄 {msg}")
-                    write_sync_status("error", msg)
-                    trigger_webhook("sync", "error", msg)
-        else:
-            if sync_with_git():
-                print(f"🔄 Workspace sync (git): pushed changes ({ts})")
-                write_sync_status("success", "Successfully pushed via git")
-            else:
-                msg = f"Workspace sync: push failed ({ts}), will retry"
-                print(f"🔄 {msg}")
-                write_sync_status("error", msg)
-                trigger_webhook("sync", "error", msg)
+        run_sync_pass(use_hf_hub)
 
 
 if __name__ == "__main__":