v1.1.0: Pre-built Docker image, huggingface_hub sync, password auth, trusted proxies

.env.example

@@ -128,6 +128,10 @@ LLM_MODEL=anthropic/claude-sonnet-4-5
 # Generate: openssl rand -hex 32
 GATEWAY_TOKEN=your_gateway_token_here
 
+# (Optional) Password auth — simpler alternative to token for casual users
+# If set, users can log in with this password instead of the token
+# OPENCLAW_PASSWORD=your_password_here
+
 # ── OPTIONAL: Telegram Integration ──
 # Get bot token from: https://t.me/BotFather
 TELEGRAM_BOT_TOKEN=your_bot_token_here
@@ -164,6 +168,15 @@ OPENCLAW_VERSION=latest
 # Health endpoint port. Default: 7861
 HEALTH_PORT=7861
 
+# Trusted proxies (comma-separated IPs)
+# Fixes "Proxy headers detected from untrusted address" behind reverse proxies
+# Only set if you see pairing/auth errors. Find IPs in Space logs (remote=x.x.x.x)
+# TRUSTED_PROXIES=10.20.31.87,10.20.26.157
+
+# Allowed origins for Control UI (comma-separated URLs)
+# Locks down the web UI to only these origins
+# ALLOWED_ORIGINS=https://your-space.hf.space
+
 # ════════════════════════════════════════════════════════════════
 # QUICK START: Only 3 secrets required!
 #   1. LLM_API_KEY    → From your LLM provider

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.1.0] - 2026-03-31
+
+### Added
+- **Pre-built Docker image** — uses `ghcr.io/openclaw/openclaw:latest` multi-stage build for much faster builds (minutes instead of 30+)
+- **Python huggingface_hub sync** — `workspace-sync.py` uses the `huggingface_hub` library for more reliable HF Dataset sync (handles auth, LFS, retries). Falls back to git-based sync automatically
+- **Password auth** — `OPENCLAW_PASSWORD` for simpler login (optional alternative to token)
+- **Trusted proxies** — `TRUSTED_PROXIES` env var fixes "Proxy headers detected from untrusted address" errors on HF Spaces
+- **Allowed origins** — `ALLOWED_ORIGINS` env var to lock down Control UI access
+- **40+ LLM providers** — Added support for OpenCode, OpenRouter, DeepSeek, Qwen, Z.ai, Moonshot, Mistral, xAI, NVIDIA, Volcengine, BytePlus, Cohere, Groq, HuggingFace Inference, and more
+- **OpenCode Zen/Go** — support for OpenCode's tested model service
+
+### Changed
+- Provider detection now uses `case` statement (cleaner, faster) with correct OpenClaw provider IDs
+- Model IDs now sourced from OpenClaw docs (not OpenRouter) for accuracy
+- Google API key env var corrected to `GEMINI_API_KEY`
+
 ## [1.0.0] - 2026-03-30
 
 ### 🎉 Initial Release

Dockerfile

@@ -1,30 +1,44 @@
-FROM node:22-slim
+# ════════════════════════════════════════════════════════════════
+# 🦞 HuggingClaw — OpenClaw Gateway for HuggingFace Spaces
+# ════════════════════════════════════════════════════════════════
+# Multi-stage build: uses pre-built OpenClaw image for fast builds
+
+# ── Stage 1: Pull pre-built OpenClaw ──
+FROM ghcr.io/openclaw/openclaw:latest AS openclaw
 
-# Version pinning (default: latest)
-ARG OPENCLAW_VERSION=latest
+# ── Stage 2: Runtime ──
+FROM node:22-slim
 
-# Install git, ca-certificates, jq, and curl
+# Install system dependencies
 RUN apt-get update && apt-get install -y \
     git \
     ca-certificates \
     jq \
     curl \
+    python3 \
+    python3-pip \
     --no-install-recommends && \
+    pip3 install --no-cache-dir --break-system-packages huggingface_hub && \
     rm -rf /var/lib/apt/lists/*
 
 # Reuse existing node user (UID 1000)
 RUN mkdir -p /home/node/app /home/node/.openclaw && \
     chown -R 1000:1000 /home/node
 
-# Install OpenClaw (version configurable via build arg)
-RUN npm install -g openclaw@${OPENCLAW_VERSION}
+# Copy pre-built OpenClaw (skips npm install entirely — much faster!)
+COPY --from=openclaw --chown=1000:1000 /app /home/node/.openclaw/openclaw-app
+
+# 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@latest
 
-# Copy files
+# Copy HuggingClaw files
 COPY --chown=1000:1000 dns-fix.js /opt/dns-fix.js
 COPY --chown=1000:1000 health-server.js /home/node/app/health-server.js
 COPY --chown=1000:1000 start.sh /home/node/app/start.sh
 COPY --chown=1000:1000 keep-alive.sh /home/node/app/keep-alive.sh
 COPY --chown=1000:1000 workspace-sync.sh /home/node/app/workspace-sync.sh
+COPY --chown=1000:1000 workspace-sync.py /home/node/app/workspace-sync.py
 RUN chmod +x /home/node/app/start.sh /home/node/app/keep-alive.sh /home/node/app/workspace-sync.sh
 
 USER node

README.md

@@ -23,14 +23,15 @@ Works with **any LLM** (Anthropic, OpenAI, Google), connects via **Telegram**, a
 ### ✨ Features
 
 - **Zero-config** — just add 3 secrets and deploy
-- **Any LLM provider** — Claude, GPT-4, Gemini, etc.
+- **Any LLM provider** — Claude, GPT-4, Gemini, DeepSeek, Qwen, Grok, and [40+ more](#-llm-provider-setup)
+- **Fast builds** — uses pre-built OpenClaw Docker image (minutes, not 30+)
+- **Smart workspace sync** — uses `huggingface_hub` Python library (more reliable than git for HF)
 - **Built-in keep-alive** — self-pings to prevent HF sleep (no external cron needed)
-- **Auto-sync workspace** — commits + pushes changes every 10 min
 - **Auto-create backup** — creates the HF Dataset for you if it doesn't exist
 - **Graceful shutdown** — saves workspace before container dies
 - **Multi-user Telegram** — supports comma-separated user IDs for teams
 - **Health endpoint** — `/health` for monitoring
-- **Version pinning** — lock OpenClaw to a specific version
+- **Password or token auth** — choose what works for you
 - **100% HF-native** — runs entirely on HuggingFace infrastructure
 
 ---
@@ -107,6 +108,14 @@ See **`.env.example`** for the complete reference with examples.
 | `KEEP_ALIVE_INTERVAL` | `300` (5 min) | Self-ping interval. `0` = disable |
 | `SYNC_INTERVAL` | `600` (10 min) | Auto-sync interval |
 
+#### Security (Optional)
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `OPENCLAW_PASSWORD` | — | Password auth (simpler alternative to token) |
+| `TRUSTED_PROXIES` | — | Comma-separated proxy IPs (fixes auth issues behind reverse proxies) |
+| `ALLOWED_ORIGINS` | — | Comma-separated URLs to lock down Control UI |
+
 #### Advanced
 
 | Variable | Default | Purpose |
@@ -299,8 +308,9 @@ Set `HF_USERNAME` + `HF_TOKEN` and HuggingClaw handles everything:
 
 1. **Auto-creates** the dataset if it doesn't exist
 2. **Restores** workspace on every startup
-3. **Auto-syncs** changes every 10 minutes (configurable)
-4. **Saves** on shutdown (graceful SIGTERM handling)
+3. **Smart sync** — uses `huggingface_hub` Python library (handles auth, LFS, retries automatically; falls back to git if unavailable)
+4. **Auto-syncs** changes every 10 minutes (configurable via `SYNC_INTERVAL`)
+5. **Saves** on shutdown (graceful SIGTERM handling)
 
 Custom dataset name: `BACKUP_DATASET_NAME=my-custom-backup`
 
@@ -356,14 +366,14 @@ openclaw channels login --gateway https://YOUR-SPACE-URL.hf.space
 
 ```
 HuggingClaw/
-├── Dockerfile          # Runtime: Node.js + OpenClaw + curl + jq
+├── Dockerfile          # Multi-stage build with pre-built OpenClaw image
 ├── start.sh            # Config generator + validation + orchestrator
 ├── keep-alive.sh       # Self-ping to prevent HF sleep
-├── workspace-sync.sh   # Periodic workspace commit + push
+├── workspace-sync.py   # Smart sync via huggingface_hub (with git fallback)
+├── workspace-sync.sh   # Legacy git-based sync (fallback)
 ├── health-server.js    # Health endpoint (/health)
 ├── dns-fix.js          # DNS override for HF network restrictions
 ├── .env.example        # Complete configuration reference
-├── .gitignore          # Keeps secrets out of version control
 └── README.md           # You are here
 ```
 
@@ -390,7 +400,9 @@ HuggingClaw/
 
 **Space sleeping** → Check logs for `💓 Keep-alive started`. If missing, `SPACE_HOST` might not be set
 
-**Control UI blocked** → The Space URL is auto-allowlisted. Check logs for origin errors
+**"Proxy headers detected" or auth errors** → Set `TRUSTED_PROXIES` with the IPs from your Space logs (`remote=x.x.x.x`)
+
+**Control UI blocked** → Set `ALLOWED_ORIGINS=https://your-space.hf.space` or check logs for origin errors
 
 **Version issues** → Pin with `OPENCLAW_VERSION=2026.3.24` in secrets
 

start.sh

@@ -199,6 +199,25 @@ fi
 # Disable device auth (pairing) for headless Docker — token-only auth
 CONFIG_JSON=$(echo "$CONFIG_JSON" | jq ".gateway.controlUi.dangerouslyDisableDeviceAuth = true")
 
+# Password auth (optional — simpler alternative to token for casual users)
+if [ -n "$OPENCLAW_PASSWORD" ]; then
+  CONFIG_JSON=$(echo "$CONFIG_JSON" | jq ".gateway.auth.mode = \"password\" | .gateway.auth.password = \"$OPENCLAW_PASSWORD\"")
+fi
+
+# Trusted proxies (optional — fixes "Proxy headers detected from untrusted address" on HF Spaces)
+# Set TRUSTED_PROXIES as comma-separated IPs, e.g. "10.20.31.87,10.20.26.157"
+if [ -n "$TRUSTED_PROXIES" ]; then
+  PROXIES_JSON=$(echo "$TRUSTED_PROXIES" | tr ',' '\n' | sed 's/^ *//;s/ *$//' | jq -R . | jq -s .)
+  CONFIG_JSON=$(echo "$CONFIG_JSON" | jq ".gateway.trustedProxies = $PROXIES_JSON")
+fi
+
+# Allowed origins (optional — lock down Control UI to specific URLs)
+# Set ALLOWED_ORIGINS as comma-separated URLs, e.g. "https://your-space.hf.space"
+if [ -n "$ALLOWED_ORIGINS" ]; then
+  ORIGINS_JSON=$(echo "$ALLOWED_ORIGINS" | tr ',' '\n' | sed 's/^ *//;s/ *$//' | jq -R . | jq -s .)
+  CONFIG_JSON=$(echo "$CONFIG_JSON" | jq ".gateway.controlUi.allowedOrigins = $ORIGINS_JSON")
+fi
+
 # Telegram (supports multiple user IDs, comma-separated)
 if [ -n "$TELEGRAM_BOT_TOKEN" ]; then
   CONFIG_JSON=$(echo "$CONFIG_JSON" | jq '.plugins.entries.telegram = {"enabled": true}')
@@ -233,6 +252,11 @@ printf "  │  %-40s │\n" "Backup: ✅ ${HF_USERNAME}/${BACKUP_DATASET:-huggin
 else
 printf "  │  %-40s │\n" "Backup: ❌ not configured"
 fi
+if [ -n "$OPENCLAW_PASSWORD" ]; then
+printf "  │  %-40s │\n" "Auth: 🔑 password"
+else
+printf "  │  %-40s │\n" "Auth: 🔐 token"
+fi
 if [ -n "$SPACE_HOST" ]; then
 printf "  │  %-40s │\n" "Keep-alive: ✅ every ${KEEP_ALIVE_INTERVAL:-300}s"
 printf "  │  %-40s │\n" "Control UI: https://${SPACE_HOST}"
@@ -276,7 +300,13 @@ trap graceful_shutdown SIGTERM SIGINT
 # ── Start background services ──
 node /home/node/app/health-server.js &
 /home/node/app/keep-alive.sh &
-/home/node/app/workspace-sync.sh &
+
+# Use Python huggingface_hub sync if available, fallback to git-based sync
+if python3 -c "import huggingface_hub" 2>/dev/null; then
+  python3 /home/node/app/workspace-sync.py &
+else
+  /home/node/app/workspace-sync.sh &
+fi
 
 # ── Launch gateway ──
 echo "🚀 Launching OpenClaw gateway on port 7860..."

workspace-sync.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+HuggingClaw Workspace Sync — HuggingFace Hub based backup
+Uses huggingface_hub Python library instead of git for more reliable
+HF Dataset operations (handles auth, LFS, retries automatically).
+
+Falls back to git-based sync if HF_USERNAME or HF_TOKEN are not set.
+"""
+
+import os
+import sys
+import time
+import signal
+import subprocess
+from pathlib import Path
+
+WORKSPACE = Path("/home/node/.openclaw/workspace")
+INTERVAL = int(os.environ.get("SYNC_INTERVAL", "600"))
+HF_TOKEN = os.environ.get("HF_TOKEN", "")
+HF_USERNAME = os.environ.get("HF_USERNAME", "")
+BACKUP_DATASET = os.environ.get("BACKUP_DATASET_NAME", "huggingclaw-backup")
+
+running = True
+
+def signal_handler(sig, frame):
+    global running
+    running = False
+
+signal.signal(signal.SIGTERM, signal_handler)
+signal.signal(signal.SIGINT, signal_handler)
+
+
+def has_changes():
+    """Check if workspace has uncommitted changes (git-based check)."""
+    try:
+        subprocess.run(["git", "add", "-A"], cwd=WORKSPACE, capture_output=True)
+        result = subprocess.run(
+            ["git", "diff", "--cached", "--quiet"],
+            cwd=WORKSPACE, capture_output=True
+        )
+        return result.returncode != 0
+    except Exception:
+        return False
+
+
+def sync_with_hf_hub():
+    """Sync workspace using huggingface_hub library."""
+    try:
+        from huggingface_hub import HfApi, upload_folder
+
+        api = HfApi(token=HF_TOKEN)
+        repo_id = f"{HF_USERNAME}/{BACKUP_DATASET}"
+
+        # Ensure dataset exists
+        try:
+            api.repo_info(repo_id=repo_id, repo_type="dataset")
+        except Exception:
+            print(f"  📝 Creating dataset {repo_id}...")
+            try:
+                api.create_repo(repo_id=repo_id, repo_type="dataset", private=True)
+                print(f"  ✅ Dataset created: {repo_id}")
+            except Exception as e:
+                print(f"  ⚠️  Could not create dataset: {e}")
+                return False
+
+        # Upload workspace
+        upload_folder(
+            folder_path=str(WORKSPACE),
+            repo_id=repo_id,
+            repo_type="dataset",
+            token=HF_TOKEN,
+            commit_message=f"Auto-sync {time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())}",
+            ignore_patterns=[".git/*", ".git"],
+        )
+        return True
+
+    except ImportError:
+        print("  ⚠️  huggingface_hub not installed, falling back to git")
+        return False
+    except Exception as e:
+        print(f"  ⚠️  HF Hub sync failed: {e}")
+        return False
+
+
+def sync_with_git():
+    """Fallback: sync workspace using git."""
+    try:
+        ts = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        subprocess.run(["git", "add", "-A"], cwd=WORKSPACE, capture_output=True)
+        subprocess.run(
+            ["git", "commit", "-m", f"Auto-sync {ts}"],
+            cwd=WORKSPACE, capture_output=True
+        )
+        result = subprocess.run(
+            ["git", "push", "origin", "main"],
+            cwd=WORKSPACE, capture_output=True
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
+def main():
+    # Wait for workspace to initialize
+    time.sleep(30)
+
+    if not WORKSPACE.exists():
+        print("📁 Workspace sync: workspace not found, exiting.")
+        return
+
+    use_hf_hub = bool(HF_TOKEN and HF_USERNAME)
+
+    if use_hf_hub:
+        print(f"🔄 Workspace sync started (huggingface_hub): every {INTERVAL}s → {HF_USERNAME}/{BACKUP_DATASET}")
+    else:
+        git_dir = WORKSPACE / ".git"
+        if not git_dir.exists():
+            print("📁 Workspace sync: no git repo and no HF credentials, skipping.")
+            return
+        print(f"🔄 Workspace sync started (git): every {INTERVAL}s")
+
+    while running:
+        time.sleep(INTERVAL)
+        if not running:
+            break
+
+        if not has_changes():
+            continue
+
+        ts = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+        if use_hf_hub:
+            if sync_with_hf_hub():
+                print(f"🔄 Workspace sync (hf_hub): pushed changes ({ts})")
+            else:
+                # Fallback to git
+                if sync_with_git():
+                    print(f"🔄 Workspace sync (git fallback): pushed changes ({ts})")
+                else:
+                    print(f"🔄 Workspace sync: failed ({ts}), will retry")
+        else:
+            if sync_with_git():
+                print(f"🔄 Workspace sync (git): pushed changes ({ts})")
+            else:
+                print(f"🔄 Workspace sync: push failed ({ts}), will retry")
+
+
+if __name__ == "__main__":
+    main()