feat: professional README, .env.example, architecture diagram

- New .env.example with documented environment variables
(required/recommended/optional, with descriptions)
- Architecture SVG diagram as project logo
- Professional README with quick start, config reference, data flow
- Dynamic SPACE_HOST for allowedOrigins (auto-detected by HF runtime)
- OPENCLAW_DEFAULT_MODEL env var for configurable default model
- NODE_MEMORY_LIMIT env var for tuning Node.js heap size
- Remove hardcoded tao-shen-huggingclaw.hf.space from config
- Clean up Telegram env vars (prefer Control UI configuration)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -1,19 +1,99 @@
-# HuggingClaw 环境变量示例
-# 复制为 .env 后填写，或在 HF Space 的 Settings -> Repository secrets 中配置
-
-# ========== 持久化（必填）==========
-# 具有写权限的 Hugging Face Access Token
-HF_TOKEN=
-# 用于备份的 Dataset 仓库，格式: username/dataset-name
-OPENCLAW_DATASET_REPO=
-
-# ========== Telegram 机器人（可选）==========
-# TELEGRAM_BOT_TOKEN=
-# TELEGRAM_BOT_NAME=
-# TELEGRAM_ALLOW_USER=
-
-# ========== 可选 ==========
-# 同步间隔（秒），默认 120
+# ═══════════════════════════════════════════════════════════════════════════
+#  HuggingClaw — Environment Configuration
+#  Deploy OpenClaw on HuggingFace Spaces
+# ═══════════════════════════════════════════════════════════════════════════
+#
+#  Usage:
+#    Local Docker  →  cp .env.example .env  →  fill in values  →  docker run --env-file .env
+#    HF Spaces     →  Set each variable as a "Repository Secret" in Space Settings
+#
+#  Legend:
+#    [REQUIRED]      Must be set, or data persistence will not work
+#    [RECOMMENDED]   Strongly recommended for production use
+#    [OPTIONAL]      Fine-tune behavior; safe to leave empty
+#
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+# ─── SECURITY ─────────────────────────────────────────────────────────────
+#
+# Password for the Control UI dashboard.
+# Visitors can see the UI, but only users with this password can connect
+# and control the OpenClaw instance (manage agents, plugins, settings).
+#
+# [RECOMMENDED]  Default: huggingclaw
+#
+OPENCLAW_PASSWORD=huggingclaw
+
+
+# ─── DATA PERSISTENCE ────────────────────────────────────────────────────
+#
+# HuggingClaw auto-syncs the ~/.openclaw directory to a private HF Dataset
+# repo, so your conversations, settings, and credentials survive restarts.
+# Without these two variables, all data is lost when the Space restarts.
+#
+# HuggingFace Access Token with WRITE permission.
+# Create one at: https://huggingface.co/settings/tokens
+# Scopes needed: read + write access to your repos.
+#
+# [REQUIRED]
+#
+HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Target Dataset repository for data backup.
+# Format: your-username/repo-name
+# If the repo doesn't exist, HuggingClaw auto-creates it as PRIVATE.
+# Example: tao-shen/openclaw-data
+#
+# [REQUIRED]
+#
+OPENCLAW_DATASET_REPO=your-username/openclaw-data
+
+# How often (in seconds) to back up data to the Dataset repo.
+# Lower values = safer but more API calls to HuggingFace.
+#
+# [OPTIONAL]  Default: 120
+#
 # SYNC_INTERVAL=120
-# 是否启用辅助服务，默认 false
-# ENABLE_AUX_SERVICES=false
+
+
+# ─── LLM PROVIDER ────────────────────────────────────────────────────────
+#
+# OpenClaw needs at least one LLM provider to power AI conversations.
+# OpenRouter is recommended — one API key, 200+ models, free tier included.
+#
+# OpenRouter API Key
+# Get one at: https://openrouter.ai/keys
+# Free-tier models: stepfun/step-3.5-flash:free, deepseek/deepseek-chat:free
+#
+# [RECOMMENDED]
+#
+OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Default model for new conversations.
+# Must be a model available from your configured provider.
+# Format: provider/model-id  (e.g., openrouter/deepseek/deepseek-chat:free)
+#
+# [OPTIONAL]  Default: openrouter/stepfun/step-3.5-flash:free
+#
+# OPENCLAW_DEFAULT_MODEL=openrouter/deepseek/deepseek-chat:free
+
+
+# ─── PERFORMANCE ──────────────────────────────────────────────────────────
+#
+# Node.js heap memory limit in MB.
+# HF free tier provides 16 GB RAM. Default 512 MB is enough for most cases.
+# Increase if you run complex agent workflows or handle large conversations.
+#
+# [OPTIONAL]  Default: 512
+#
+# NODE_MEMORY_LIMIT=512
+
+
+# ─── LOCALE ───────────────────────────────────────────────────────────────
+#
+# Timezone for log timestamps and scheduled tasks.
+#
+# [OPTIONAL]  Default: UTC
+#
+# TZ=Asia/Shanghai

README.md

@@ -10,55 +10,117 @@ short_description: Deploy OpenClaw on HuggingFace Spaces
 app_port: 7860
 ---
 
-# HuggingClaw
+<div align="center">
+  <img src="assets/architecture.svg" alt="HuggingClaw Architecture" width="720"/>
+  <br/><br/>
+  <strong>The easiest way to deploy <a href="https://github.com/openclaw/openclaw">OpenClaw</a> on the cloud</strong>
+  <br/>
+  <sub>Zero hardware · Always online · Auto-persistent · One-click deploy</sub>
+  <br/><br/>
+
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+  [![HF Spaces](https://img.shields.io/badge/%F0%9F%A4%97-HuggingFace%20Spaces-blue)](https://huggingface.co/spaces/tao-shen/HuggingClaw)
+</div>
 
-**Deploy [OpenClaw](https://github.com/openclaw/openclaw) on HuggingFace Spaces** — no hardware required.
+---
+
+## What is HuggingClaw?
+
+[OpenClaw](https://github.com/openclaw/openclaw) is a self-hosted AI assistant platform with Telegram, WhatsApp integration and a web-based Control UI. It's powerful — but traditionally requires your own server.
 
-OpenClaw is a self-hosted AI assistant platform with Telegram, WhatsApp integration and a web-based Control UI. HuggingClaw packages it for one-click cloud deployment on HuggingFace Spaces.
+**HuggingClaw** solves this by packaging OpenClaw for **one-click cloud deployment** on HuggingFace Spaces. No server, no GPU, no DevOps — just fork, configure secrets, and go.
 
-## Why HuggingFace Spaces?
+### Why HuggingFace Spaces?
 
-- **Zero hardware** — runs on HF's free CPU tier
-- **Always online** — no need to keep your computer running
-- **Persistent storage** — auto-syncs data to a HF Dataset repo
-- **HTTPS built-in** — secure WebSocket connections out of the box
-- **One-click deploy** — fork this Space, set secrets, done
+| Feature | Detail |
+|---------|--------|
+| **Free compute** | Runs on HF's free CPU tier (2 vCPU, 16 GB RAM) |
+| **Always online** | No need to keep your computer running |
+| **Auto-persistent** | Syncs data to a private HF Dataset repo on schedule |
+| **HTTPS built-in** | Secure WebSocket connections out of the box |
+| **One-click deploy** | Fork → set secrets → done |
 
 ## Quick Start
 
-### 1. Fork this Space
+### 1. Duplicate this Space
 
-Click **Duplicate this Space** on HuggingFace.
+Click **Duplicate this Space** on the [HuggingClaw Space page](https://huggingface.co/spaces/tao-shen/HuggingClaw).
 
 ### 2. Set Secrets
 
-Go to **Settings > Repository secrets** and add:
+Go to **Settings → Repository secrets** and configure:
 
-| Secret | Required | Description |
-|--------|:--------:|-------------|
+| Secret | Status | Description |
+|--------|:------:|-------------|
 | `OPENCLAW_PASSWORD` | Recommended | Password for the Control UI (default: `huggingclaw`) |
-| `HF_TOKEN` | Yes | HF Access Token with write permission (for data persistence) |
-| `OPENCLAW_DATASET_REPO` | Yes | Dataset repo for backup, e.g. `your-name/openclaw-data` |
-| `OPENROUTER_API_KEY` | No | [OpenRouter](https://openrouter.ai) API key for LLM access |
-| `TELEGRAM_BOT_TOKEN` | No | Telegram bot token from [@BotFather](https://t.me/BotFather) |
-| `TELEGRAM_BOT_NAME` | No | Telegram bot username |
-| `TELEGRAM_ALLOW_USER` | No | Telegram username allowed to chat |
+| `HF_TOKEN` | **Required** | HF Access Token with write permission ([create one](https://huggingface.co/settings/tokens)) |
+| `OPENCLAW_DATASET_REPO` | **Required** | Dataset repo for backup, e.g. `your-name/openclaw-data` |
+| `OPENROUTER_API_KEY` | Recommended | [OpenRouter](https://openrouter.ai) API key for LLM access |
+
+> For the full list of environment variables, see [`.env.example`](.env.example).
 
 ### 3. Open the Control UI
 
-Visit your Space URL. Enter the password in the settings panel to connect.
+Visit your Space URL. Click the settings icon, enter your password, and connect.
+
+Messaging integrations (Telegram, WhatsApp) can be configured directly inside the Control UI after connecting.
+
+## Configuration
+
+HuggingClaw is configured entirely through **environment variables**. A fully documented template is provided in [`.env.example`](.env.example).
+
+| Category | Variables | Purpose |
+|----------|-----------|---------|
+| **Security** | `OPENCLAW_PASSWORD` | Protect the Control UI with a password |
+| **Persistence** | `HF_TOKEN`, `OPENCLAW_DATASET_REPO`, `SYNC_INTERVAL` | Auto-backup to HF Dataset |
+| **LLM** | `OPENROUTER_API_KEY`, `OPENCLAW_DEFAULT_MODEL` | Power AI conversations |
+| **Performance** | `NODE_MEMORY_LIMIT` | Tune Node.js memory usage |
+| **Locale** | `TZ` | Set timezone for logs |
+
+For local development, copy the template and fill in your values:
+
+```bash
+cp .env.example .env
+# Edit .env with your values
+```
 
 ## Architecture
 
 ```
 HuggingFace Space (Docker)
-├── OpenClaw (Node.js)        — AI assistant engine
-│   ├── Control UI            — Web dashboard (port 7860)
-│   ├── Telegram extension    — Bot integration
-│   └── WhatsApp extension    — Messaging integration
-├── sync_hf.py                — Auto-sync ~/.openclaw ↔ HF Dataset
-├── dns-resolve.py            — DNS pre-resolution for WhatsApp
-└── entrypoint.sh             — Startup orchestration
+│
+├── OpenClaw Engine (Node.js)
+│   ├── Control UI ─────── Web dashboard (port 7860)
+│   ├── Telegram Plugin ── Bot integration
+│   ├── WhatsApp Plugin ── Messaging integration
+│   └── Agent Workflows ── AI assistants
+│
+├── Sync Service (sync_hf.py)
+│   └── Auto-backup ~/.openclaw ↔ HF Dataset repo
+│
+├── DNS Resolver (dns-resolve.py)
+│   └── Pre-resolve WhatsApp domains via DoH
+│
+└── Entrypoint (entrypoint.sh)
+    └── Orchestrate startup sequence
+```
+
+**Data flow:**
+
+```
+Users (Browser/Telegram/WhatsApp)
+          │
+          ▼
+   ┌─────────────┐     ┌───────────────┐
+   │   OpenClaw   │────▶│  LLM Provider  │
+   │   Engine     │◀────│  (OpenRouter)  │
+   └──────┬──────┘     └───────────────┘
+          │
+          ▼
+   ┌─────────────┐     ┌───────────────┐
+   │    Sync      │────▶│  HF Dataset    │
+   │   Service    │◀────│  (Backup)      │
+   └─────────────┘     └───────────────┘
 ```
 
 ## Local Development
@@ -66,21 +128,26 @@ HuggingFace Space (Docker)
 ```bash
 git clone https://huggingface.co/spaces/tao-shen/HuggingClaw
 cd HuggingClaw
+
+# Configure
+cp .env.example .env
+# Edit .env — at minimum set HF_TOKEN and OPENCLAW_DATASET_REPO
+
+# Build and run
 docker build -t huggingclaw .
-docker run --rm -p 7860:7860 \
-  -e OPENCLAW_PASSWORD=your-password \
-  -e HF_TOKEN=hf_xxx \
-  -e OPENCLAW_DATASET_REPO=your-name/openclaw-data \
-  huggingclaw
+docker run --rm -p 7860:7860 --env-file .env huggingclaw
 ```
 
 Open `http://localhost:7860` in your browser.
 
 ## Security
 
-- **Password-protected** — the Control UI requires a password to connect
-- **Secrets stay server-side** — API keys are never exposed to the browser
-- **CSP headers** — Content Security Policy restricts script/resource loading
+- **Password-protected** — the Control UI requires a password to connect and manage the instance
+- **Secrets stay server-side** — API keys and tokens are never exposed to the browser
+- **CSP headers** — Content Security Policy restricts script and resource loading
+- **Private backups** — the Dataset repo is created as private by default
+
+> **Tip:** Change the default password from `huggingclaw` to something unique by setting the `OPENCLAW_PASSWORD` secret.
 
 ## License
 

openclaw.json

@@ -12,8 +12,7 @@
       "dangerouslyDisableDeviceAuth": true,
       "allowedOrigins": [
         "https://huggingface.co",
-        "https://*.hf.space",
-        "https://tao-shen-huggingclaw.hf.space"
+        "https://*.hf.space"
       ]
     }
   },

scripts/entrypoint.sh

@@ -16,8 +16,13 @@ DNS_START=$(date +%s)
 ) &
 DNS_PID=$!
 
+# ── Node.js memory limit ──────────────────────────────────────────────────
+NODE_MEMORY_LIMIT="${NODE_MEMORY_LIMIT:-512}"
+export NODE_OPTIONS="${NODE_OPTIONS:+$NODE_OPTIONS }--max-old-space-size=$NODE_MEMORY_LIMIT"
+echo "[entrypoint] Node.js memory limit: ${NODE_MEMORY_LIMIT}MB"
+
 # Enable Node.js DNS fix (will use resolved file when ready)
-export NODE_OPTIONS="${NODE_OPTIONS:+$NODE_OPTIONS }--require /home/node/scripts/dns-fix.cjs"
+export NODE_OPTIONS="${NODE_OPTIONS} --require /home/node/scripts/dns-fix.cjs"
 
 # ── Extensions symlink ──────────────────────────────────────────────────────
 SYMLINK_START=$(date +%s)

scripts/sync_hf.py

@@ -57,16 +57,24 @@ APP_DIR       = Path("/app/openclaw")
 # Use ".openclaw" - directly read/write the .openclaw folder in dataset
 DATASET_PATH = ".openclaw"
 
+# Telegram credentials (backward-compatible; prefer configuring via Control UI)
 TELEGRAM_BOT_TOKEN  = os.environ.get("TELEGRAM_BOT_TOKEN", "")
 TELEGRAM_BOT_NAME   = os.environ.get("TELEGRAM_BOT_NAME", "")
 TELEGRAM_ALLOW_USER = os.environ.get("TELEGRAM_ALLOW_USER", "")
 
-# OpenRouter API key for free models (must be set via environment variable)
+# OpenRouter API key for LLM access
 OPENROUTER_API_KEY = os.environ.get("OPENROUTER_API_KEY", "")
 
 # Gateway password (override via HF Secret OPENCLAW_PASSWORD)
 OPENCLAW_PASSWORD = os.environ.get("OPENCLAW_PASSWORD", "huggingclaw")
 
+# Default model for new conversations
+OPENCLAW_DEFAULT_MODEL = os.environ.get("OPENCLAW_DEFAULT_MODEL", "openrouter/stepfun/step-3.5-flash:free")
+
+# HF Spaces built-in env vars (auto-set by HF runtime)
+SPACE_HOST = os.environ.get("SPACE_HOST", "")   # e.g. "tao-shen-huggingclaw.hf.space"
+SPACE_ID   = os.environ.get("SPACE_ID", "")      # e.g. "tao-shen/HuggingClaw"
+
 SYNC_INTERVAL = int(os.environ.get("SYNC_INTERVAL", "120"))
 
 # Setup logging
@@ -334,6 +342,14 @@ class OpenClawFullSync:
             if not OPENCLAW_PASSWORD:
                 print("[SYNC] WARNING: OPENCLAW_PASSWORD not set! Gateway will auto-generate a random token.")
             auth = {"password": OPENCLAW_PASSWORD} if OPENCLAW_PASSWORD else {}
+            # Dynamic allowedOrigins from SPACE_HOST (auto-set by HF runtime)
+            allowed_origins = [
+                "https://huggingface.co",
+                "https://*.hf.space",
+            ]
+            if SPACE_HOST:
+                allowed_origins.append(f"https://{SPACE_HOST}")
+                print(f"[SYNC] SPACE_HOST detected: {SPACE_HOST}")
             data["gateway"] = {
                 "mode": "local",
                 "bind": "lan",
@@ -343,14 +359,10 @@ class OpenClawFullSync:
                 "controlUi": {
                     "allowInsecureAuth": True,
                     "dangerouslyDisableDeviceAuth": True,
-                    "allowedOrigins": [
-                        "https://huggingface.co",
-                        "https://*.hf.space",
-                        "https://tao-shen-huggingclaw.hf.space"
-                    ]
+                    "allowedOrigins": allowed_origins
                 }
             }
-            print(f"[SYNC] Set gateway config (auth={'password' if OPENCLAW_PASSWORD else 'auto-generated'}, trustedProxies=all)")
+            print(f"[SYNC] Set gateway config (auth={'password' if OPENCLAW_PASSWORD else 'auto-generated'}, origins={len(allowed_origins)})")
 
             # Ensure agents defaults
             data.setdefault("agents", {}).setdefault("defaults", {}).setdefault("model", {})
@@ -372,7 +384,7 @@ class OpenClawFullSync:
                 print("[SYNC] WARNING: OPENROUTER_API_KEY not set, skipping provider config")
             # Remove old gemini provider if present
             data["models"]["providers"].pop("gemini", None)
-            data["agents"]["defaults"]["model"]["primary"] = "openrouter/stepfun/step-3.5-flash:free"
+            data["agents"]["defaults"]["model"]["primary"] = OPENCLAW_DEFAULT_MODEL
 
             # Plugin whitelist (only load telegram + whatsapp to speed up startup)
             data.setdefault("plugins", {}).setdefault("entries", {})