Initial commit

.env.example

@@ -0,0 +1,185 @@
+# ════════════════════════════════════════════════════════════════
+# 🦞 HuggingClaw — OpenClaw Gateway for HuggingFace Spaces
+# ════════════════════════════════════════════════════════════════
+# Copy this file to .env and fill in your values.
+# For local development: cp .env.example .env && nano .env
+
+# ── REQUIRED: Core Configuration ──
+# [REQUIRED] LLM provider API key
+# - Anthropic: sk-ant-v0-...
+# - OpenAI: sk-...
+# - Google: AIzaSy...
+# - OpenRouter: sk-or-v1-... (300+ models via single key)
+LLM_API_KEY=your_api_key_here
+
+# [REQUIRED] LLM model to use (format: provider/model-name)
+# Auto-detects provider from prefix — any provider is supported!
+# Provider IDs from OpenClaw docs: docs.openclaw.ai/concepts/model-providers
+#
+# ── Core Providers ──
+#
+# Anthropic (ANTHROPIC_API_KEY):
+#   - anthropic/claude-opus-4-6
+#   - anthropic/claude-sonnet-4-6
+#   - anthropic/claude-sonnet-4-5
+#   - anthropic/claude-haiku-4-5
+#
+# OpenAI (OPENAI_API_KEY):
+#   - openai/gpt-5.4-pro
+#   - openai/gpt-5.4
+#   - openai/gpt-5.4-mini
+#   - openai/gpt-5.4-nano
+#   - openai/gpt-4.1
+#   - openai/gpt-4.1-mini
+#
+# Google Gemini (GEMINI_API_KEY):
+#   - google/gemini-3.1-pro-preview
+#   - google/gemini-3-flash-preview
+#   - google/gemini-2.5-pro
+#   - google/gemini-2.5-flash
+#
+# DeepSeek (DEEPSEEK_API_KEY):
+#   - deepseek/deepseek-v3.2
+#   - deepseek/deepseek-r1-0528
+#   - deepseek/deepseek-r1
+#
+# ── OpenCode Providers ──
+#
+# OpenCode Zen — tested & verified models (OPENCODE_API_KEY):
+#   - opencode/claude-opus-4-6
+#   - opencode/gpt-5.4
+#   Get key from: https://opencode.ai/auth
+#
+# OpenCode Go — low-cost open models (OPENCODE_API_KEY):
+#   - opencode-go/kimi-k2.5
+#
+# ── Gateway/Router Providers ──
+#
+# OpenRouter — 300+ models via single API key (OPENROUTER_API_KEY):
+#   - openrouter/anthropic/claude-sonnet-4-6
+#   - openrouter/openai/gpt-5.4
+#   - openrouter/deepseek/deepseek-v3.2
+#   - openrouter/meta-llama/llama-3.3-70b-instruct:free
+#   Get key from: https://openrouter.ai
+#
+# Kilo Gateway (KILOCODE_API_KEY):
+#   - kilocode/anthropic/claude-opus-4.6
+#
+# ── Chinese/Asian Providers ──
+#
+# Z.ai / GLM (ZAI_API_KEY) — OpenClaw normalizes z-ai/z.ai → zai:
+#   - zai/glm-5
+#   - zai/glm-5-turbo
+#   - zai/glm-4.7
+#   - zai/glm-4.7-flash
+#
+# Moonshot / Kimi (MOONSHOT_API_KEY):
+#   - moonshot/kimi-k2.5
+#   - moonshot/kimi-k2-thinking
+#
+# MiniMax (MINIMAX_API_KEY):
+#   - minimax/minimax-m2.7
+#   - minimax/minimax-m2.5
+#
+# Xiaomi / MiMo (XIAOMI_API_KEY):
+#   - xiaomi/mimo-v2-pro
+#   - xiaomi/mimo-v2-omni
+#
+# Volcengine / Doubao (VOLCANO_ENGINE_API_KEY):
+#   - volcengine/doubao-seed-1-8-251228
+#   - volcengine/kimi-k2-5-260127
+#
+# BytePlus — international (BYTEPLUS_API_KEY):
+#   - byteplus/seed-1-8-251228
+#
+# ── Western Providers ──
+#
+# Mistral (MISTRAL_API_KEY):
+#   - mistral/mistral-large-latest
+#   - mistral/mistral-small-2603
+#   - mistral/devstral-medium
+#
+# xAI / Grok (XAI_API_KEY):
+#   - xai/grok-4.20-beta
+#   - xai/grok-4
+#
+# NVIDIA (NVIDIA_API_KEY):
+#   - nvidia/nemotron-3-super-120b-a12b
+#
+# Groq (GROQ_API_KEY):
+#   - groq/mixtral-8x7b-32768
+#
+# Cohere (COHERE_API_KEY):
+#   - cohere/command-a
+#
+# Together (TOGETHER_API_KEY):
+#   - together/meta-llama/llama-3.3-70b-instruct
+#
+# Cerebras (CEREBRAS_API_KEY):
+#   - cerebras/zai-glm-4.7
+#
+# HuggingFace Inference (HUGGINGFACE_HUB_TOKEN):
+#   - huggingface/deepseek-ai/DeepSeek-R1
+#
+# Or any other OpenClaw-supported provider (format: provider/model-name)
+LLM_MODEL=anthropic/claude-sonnet-4-5
+
+# [REQUIRED] Gateway authentication token
+# 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
+
+# Single user ID (from https://t.me/userinfobot)
+TELEGRAM_USER_ID=123456789
+
+# Multiple user IDs (comma-separated for team access)
+# TELEGRAM_USER_IDS=123456789,987654321,555555555
+
+# ── OPTIONAL: Workspace Backup to HF Dataset ──
+HF_USERNAME=your_hf_username
+HF_TOKEN=hf_your_token_here
+
+# Backup dataset name (auto-created if missing)
+# Default: huggingclaw-backup
+BACKUP_DATASET_NAME=huggingclaw-backup
+
+# Git commit identity for workspace syncs
+WORKSPACE_GIT_USER=openclaw@example.com
+WORKSPACE_GIT_NAME=OpenClaw Bot
+
+# ── OPTIONAL: Background Services ──
+# 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
+
+# ── OPTIONAL: Advanced ──
+# Pin OpenClaw version. Default: latest
+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
+#   2. LLM_MODEL      → Pick a model above
+#   3. GATEWAY_TOKEN   → Run: openssl rand -hex 32
+# ════════════════════════════════════════════════════════════════

CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+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
+
+#### Features
+- **Any LLM provider** — Anthropic (Claude), OpenAI (GPT-4), Google (Gemini)
+- **Telegram integration** — connect via @BotFather, supports multiple users
+- **Built-in keep-alive** — self-pings to prevent HF Spaces 48h sleep
+- **Auto-sync workspace** — commits + pushes to HF Dataset every 10 min
+- **Auto-create backup** — creates HF Dataset automatically on first run
+- **Graceful shutdown** — saves workspace before container stops
+- **Health endpoint** — `/health` on port 7861 for monitoring
+- **DNS fix** — bypasses HF Spaces internal DNS restrictions
+- **Version pinning** — lock OpenClaw to a specific version
+- **Startup banner** — clean summary of all running services
+- **Zero-config defaults** — just 2 secrets to get started
+
+#### Architecture
+- `start.sh` — config generator + validation + orchestrator
+- `keep-alive.sh` — self-ping background service
+- `workspace-sync.sh` — periodic workspace backup
+- `health-server.js` — lightweight health endpoint
+- `dns-fix.js` — DNS override for HF network restrictions

CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+**Positive behavior includes:**
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+**Unacceptable behavior includes:**
+- Trolling, insulting, or derogatory comments
+- Public or private harassment
+- Publishing others' private information without permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainer. All complaints will be reviewed and investigated.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.0.

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to HuggingClaw
+
+Thanks for your interest in contributing! 🦞
+
+## How to Contribute
+
+### Bug Reports
+- Open an issue with a clear description
+- Include your HF Space logs if possible
+- Mention which LLM provider you're using
+
+### Feature Requests
+- Open an issue with the `enhancement` label
+- Describe the use case — why is this needed?
+
+### Pull Requests
+1. Fork the repo
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes
+4. Test locally with Docker: `docker build -t huggingclaw . && docker run -p 7860:7860 --env-file .env huggingclaw`
+5. Commit with a clear message
+6. Push and open a PR
+
+### Code Style
+- Shell scripts: use `set -e`, quote variables, comment non-obvious logic
+- Keep it simple — this project should stay easy to understand
+- No unnecessary dependencies
+
+### Testing
+- Test with at least one LLM provider (Anthropic, OpenAI, or Google)
+- Test with and without Telegram enabled
+- Test with and without workspace backup enabled
+- Verify keep-alive and auto-sync work
+
+## Development Setup
+
+```bash
+cp .env.example .env
+# Fill in your values
+docker build -t huggingclaw .
+docker run -p 7860:7860 --env-file .env huggingclaw
+```
+
+## Questions?
+
+Open an issue or start a discussion. We're friendly! 🤝

Dockerfile

@@ -0,0 +1,53 @@
+# ════════════════════════════════════════════════════════════════
+# 🦞 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
+
+# ── Stage 2: Runtime ──
+FROM node:22-slim
+
+# 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
+
+# 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 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.py /home/node/app/workspace-sync.py
+RUN chmod +x /home/node/app/start.sh /home/node/app/keep-alive.sh
+
+USER node
+
+ENV HOME=/home/node \
+    PATH=/home/node/.local/bin:/usr/local/bin:$PATH \
+    NODE_OPTIONS="--require /opt/dns-fix.js"
+
+WORKDIR /home/node/app
+
+EXPOSE 7860
+
+CMD ["/home/node/app/start.sh"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Somrat Sorkar (@somratpro)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,426 @@
+---
+title: HuggingClaw
+emoji: 🦞
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: true
+---
+
+<!-- Badges -->
+[![GitHub Stars](https://img.shields.io/github/stars/somratpro/huggingclaw?style=flat-square)](https://github.com/somratpro/huggingclaw)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![HF Space](https://img.shields.io/badge/🤗%20HuggingFace-Space-blue?style=flat-square)](https://huggingface.co/spaces)
+[![OpenClaw](https://img.shields.io/badge/OpenClaw-Gateway-red?style=flat-square)](https://github.com/openclaw/openclaw)
+
+# 🦞 HuggingClaw
+
+Run your own **always-on AI assistant** on HuggingFace Spaces — for free.
+
+Works with **any LLM** (Anthropic, OpenAI, Google), connects via **Telegram**, and persists your workspace to **HF Datasets** automatically.
+
+### ✨ Features
+
+- **Zero-config** — just add 3 secrets and deploy
+- **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-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
+- **Password or token auth** — choose what works for you
+- **100% HF-native** — runs entirely on HuggingFace infrastructure
+
+---
+
+## 🚀 Quick Start
+
+### 1. Duplicate this Space
+[![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 → name it → set to **Private**
+
+### 2. Add Required Secrets
+Go to **Settings → Secrets**:
+
+| Secret | Value |
+|--------|-------|
+| `LLM_API_KEY` | Your API key ([Anthropic](https://console.anthropic.com/) / [OpenAI](https://platform.openai.com/) / [Google](https://ai.google.dev/)) |
+| `LLM_MODEL` | Model to use (e.g. `google/gemini-2.5-flash`, `anthropic/claude-sonnet-4-5`, `openai/gpt-4`) |
+| `GATEWAY_TOKEN` | Run `openssl rand -hex 32` to generate |
+
+### 3. Deploy
+That's it! The Space builds and starts automatically.
+
+### 4. (Optional) Add Telegram
+| Secret | Value |
+|--------|-------|
+| `TELEGRAM_BOT_TOKEN` | From [@BotFather](https://t.me/BotFather) |
+| `TELEGRAM_USER_ID` | Your user ID ([how to find](https://t.me/userinfobot)) |
+
+### 5. (Optional) Enable Workspace Backup
+| Secret | Value |
+|--------|-------|
+| `HF_USERNAME` | Your HuggingFace username |
+| `HF_TOKEN` | [HF token](https://huggingface.co/settings/tokens) with write access |
+
+The backup dataset (`huggingclaw-backup`) is **created automatically** — no manual setup needed.
+
+---
+
+## 📋 All Configuration Options
+
+See **`.env.example`** for the complete reference with examples.
+
+#### Required
+
+| Variable | Purpose |
+|----------|---------|
+| `LLM_API_KEY` | LLM provider API key |
+| `LLM_MODEL` | Model to use (e.g. `google/gemini-2.5-flash`, `anthropic/claude-sonnet-4-5`, `openai/gpt-4`) — auto-detects provider from prefix |
+| `GATEWAY_TOKEN` | Gateway auth token |
+
+#### Telegram
+
+| Variable | Purpose |
+|----------|---------|
+| `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather |
+| `TELEGRAM_USER_ID` | Single user allowlist |
+| `TELEGRAM_USER_IDS` | Multiple users (comma-separated): `123,456,789` |
+
+#### Workspace Backup
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `HF_USERNAME` | — | Your HF username |
+| `HF_TOKEN` | — | HF token (write access) |
+| `BACKUP_DATASET_NAME` | `huggingclaw-backup` | Dataset name (auto-created!) |
+| `WORKSPACE_GIT_USER` | `openclaw@example.com` | Git commit email |
+| `WORKSPACE_GIT_NAME` | `OpenClaw Bot` | Git commit name |
+
+#### Background Services
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `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 |
+|----------|---------|---------|
+| `OPENCLAW_VERSION` | `latest` | Pin OpenClaw version |
+| `HEALTH_PORT` | `7861` | Health endpoint port |
+
+---
+
+## 🤖 LLM Provider Setup
+
+Just set `LLM_MODEL` with the correct provider prefix — **any provider is supported**! The provider is auto-detected from the model name. All provider IDs from [OpenClaw docs](https://docs.openclaw.ai/concepts/model-providers).
+
+### Anthropic (Claude)
+```
+LLM_API_KEY=sk-ant-v0-...
+LLM_MODEL=anthropic/claude-sonnet-4-5
+```
+Models: `anthropic/claude-opus-4-6` · `anthropic/claude-sonnet-4-6` · `anthropic/claude-sonnet-4-5` · `anthropic/claude-haiku-4-5`
+
+### OpenAI
+```
+LLM_API_KEY=sk-...
+LLM_MODEL=openai/gpt-5.4
+```
+Models: `openai/gpt-5.4-pro` · `openai/gpt-5.4` · `openai/gpt-5.4-mini` · `openai/gpt-5.4-nano` · `openai/gpt-4.1` · `openai/gpt-4.1-mini`
+
+### Google (Gemini)
+```
+LLM_API_KEY=AIzaSy...
+LLM_MODEL=google/gemini-2.5-flash
+```
+Models: `google/gemini-3.1-pro-preview` · `google/gemini-3-flash-preview` · `google/gemini-2.5-pro` · `google/gemini-2.5-flash`
+
+### DeepSeek
+```
+LLM_API_KEY=sk-...
+LLM_MODEL=deepseek/deepseek-v3.2
+```
+Models: `deepseek/deepseek-v3.2` · `deepseek/deepseek-r1-0528` · `deepseek/deepseek-r1`
+Get key from: [DeepSeek Platform](https://platform.deepseek.com)
+
+### OpenCode Zen (tested & verified models)
+```
+LLM_API_KEY=your_opencode_api_key
+LLM_MODEL=opencode/claude-opus-4-6
+```
+Models: `opencode/claude-opus-4-6` · `opencode/gpt-5.4`
+Get key from: [OpenCode.ai](https://opencode.ai/auth)
+
+### OpenCode Go (low-cost open models)
+```
+LLM_API_KEY=your_opencode_api_key
+LLM_MODEL=opencode-go/kimi-k2.5
+```
+Get key from: [OpenCode.ai](https://opencode.ai/auth)
+
+### Z.ai (GLM)
+```
+LLM_API_KEY=your_zai_api_key
+LLM_MODEL=zai/glm-5
+```
+Models: `zai/glm-5` · `zai/glm-5-turbo` · `zai/glm-4.7` · `zai/glm-4.7-flash`
+Get key from: [Z.ai](https://z.ai) · Note: `z-ai/` and `z.ai/` prefixes auto-normalize to `zai/`
+
+### Moonshot (Kimi)
+```
+LLM_API_KEY=sk-...
+LLM_MODEL=moonshot/kimi-k2.5
+```
+Models: `moonshot/kimi-k2.5` · `moonshot/kimi-k2-thinking`
+Get key from: [Moonshot API](https://platform.moonshot.cn)
+
+### Mistral
+```
+LLM_API_KEY=your_mistral_api_key
+LLM_MODEL=mistral/mistral-large-latest
+```
+Models: `mistral/mistral-large-latest` · `mistral/mistral-small-2603` · `mistral/devstral-medium` · `mistral/codestral-2508`
+Get key from: [Mistral Console](https://console.mistral.ai)
+
+### xAI (Grok)
+```
+LLM_API_KEY=your_xai_api_key
+LLM_MODEL=xai/grok-4.20-beta
+```
+Models: `xai/grok-4.20-beta` · `xai/grok-4` · `xai/grok-4.1-fast`
+Get key from: [xAI Console](https://console.x.ai)
+
+### MiniMax
+```
+LLM_API_KEY=your_minimax_api_key
+LLM_MODEL=minimax/minimax-m2.7
+```
+Models: `minimax/minimax-m2.7` · `minimax/minimax-m2.5`
+Get key from: [MiniMax Platform](https://platform.minimax.io)
+
+### NVIDIA
+```
+LLM_API_KEY=your_nvidia_api_key
+LLM_MODEL=nvidia/nemotron-3-super-120b-a12b
+```
+Get key from: [NVIDIA API](https://api.nvidia.com)
+
+### Xiaomi (MiMo)
+```
+LLM_API_KEY=your_xiaomi_api_key
+LLM_MODEL=xiaomi/mimo-v2-pro
+```
+Models: `xiaomi/mimo-v2-pro` · `xiaomi/mimo-v2-omni`
+
+### Volcengine (Doubao / ByteDance)
+```
+LLM_API_KEY=your_volcengine_api_key
+LLM_MODEL=volcengine/doubao-seed-1-8-251228
+```
+Models: `volcengine/doubao-seed-1-8-251228` · `volcengine/kimi-k2-5-260127` · `volcengine/glm-4-7-251222`
+Get key from: [Volcengine](https://www.volcengine.com)
+
+### Groq
+```
+LLM_API_KEY=your_groq_api_key
+LLM_MODEL=groq/mixtral-8x7b-32768
+```
+Get key from: [Groq Console](https://console.groq.com)
+
+### Cohere
+```
+LLM_API_KEY=your_cohere_api_key
+LLM_MODEL=cohere/command-a
+```
+Get key from: [Cohere Dashboard](https://dashboard.cohere.com)
+
+### HuggingFace Inference
+```
+LLM_API_KEY=hf_your_token
+LLM_MODEL=huggingface/deepseek-ai/DeepSeek-R1
+```
+Get key from: [HuggingFace Tokens](https://huggingface.co/settings/tokens)
+
+### OpenRouter (300+ models via single API key)
+```
+LLM_API_KEY=sk-or-v1-...
+LLM_MODEL=openrouter/anthropic/claude-sonnet-4-6
+```
+With OpenRouter, you can access **every model above** with a single API key! Just prefix with `openrouter/`:
+- `openrouter/anthropic/claude-sonnet-4-6` — Anthropic Claude
+- `openrouter/openai/gpt-5.4` — OpenAI
+- `openrouter/deepseek/deepseek-v3.2` — DeepSeek
+- `openrouter/google/gemini-2.5-flash` — Google Gemini
+- `openrouter/meta-llama/llama-3.3-70b-instruct:free` — Llama (free!)
+- `openrouter/moonshotai/kimi-k2.5` — Moonshot Kimi
+- `openrouter/z-ai/glm-5-turbo` — Z.ai GLM
+
+Get key from: [OpenRouter.ai](https://openrouter.ai) · [Full model list](https://openrouter.ai/models)
+
+### Kilo Gateway
+```
+LLM_API_KEY=your_kilocode_api_key
+LLM_MODEL=kilocode/anthropic/claude-opus-4.6
+```
+Get key from: [Kilo.ai](https://kilo.ai)
+
+### Any Other Provider
+HuggingClaw supports **any LLM provider** that OpenClaw supports. Just use:
+```
+LLM_API_KEY=your_api_key
+LLM_MODEL=provider/model-name
+```
+The provider prefix is auto-detected and mapped to the appropriate environment variable.
+
+Full provider list: [OpenClaw Model Providers](https://docs.openclaw.ai/concepts/model-providers) · [OpenCode Providers](https://opencode.ai/docs/providers)
+
+---
+
+## 📱 Telegram Setup
+
+1. Message [@BotFather](https://t.me/BotFather) → `/newbot` → copy the token
+2. Message [@userinfobot](https://t.me/userinfobot) to get your user ID
+3. Add secrets: `TELEGRAM_BOT_TOKEN` and `TELEGRAM_USER_ID`
+4. Restart the Space → DM your bot 🎉
+
+**Multiple users?** Use `TELEGRAM_USER_IDS=123,456,789` (comma-separated)
+
+---
+
+## 💾 Workspace Backup
+
+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. **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`
+
+---
+
+## 💓 How It Stays Alive
+
+HF Spaces sleeps after 48h of no HTTP requests. HuggingClaw prevents this with:
+
+- **Self-ping** — pings its own URL every 5 min (uses HF's `SPACE_HOST` env var)
+- **Health endpoint** — returns `200 OK` with uptime info
+- **Zero dependencies** — no external cron, no third-party pinger
+
+Your Space runs forever, powered entirely by HF. 🎯
+
+---
+
+## 💻 Local Development
+
+```bash
+git clone https://github.com/somratpro/huggingclaw.git
+cd huggingclaw
+cp .env.example .env
+nano .env  # fill in your values
+```
+
+**Docker:**
+```bash
+docker build -t huggingclaw .
+docker run -p 7860:7860 --env-file .env huggingclaw
+```
+
+**Without Docker:**
+```bash
+npm install -g openclaw@latest
+export $(cat .env | xargs)
+bash start.sh
+```
+
+---
+
+## 🔗 Connect via CLI
+
+```bash
+npm install -g openclaw@latest
+openclaw channels login --gateway https://YOUR-SPACE-URL.hf.space
+# Enter your GATEWAY_TOKEN when prompted
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+HuggingClaw/
+├── 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.py   # Smart sync via huggingface_hub (with git fallback)
+├── health-server.js    # Health endpoint (/health)
+├── dns-fix.js          # DNS override for HF network restrictions
+├── .env.example        # Complete configuration reference
+└── README.md           # You are here
+```
+
+**Startup flow:**
+1. Validate secrets → fail fast with clear errors
+2. Validate HF token → warn if expired
+3. Auto-create backup dataset if missing
+4. Restore workspace from HF Dataset
+5. Generate `openclaw.json` config from env vars
+6. Print startup summary
+7. Start background services (keep-alive, auto-sync)
+8. Launch OpenClaw gateway
+9. On SIGTERM → save workspace → exit cleanly
+
+---
+
+## 🐛 Troubleshooting
+
+**Missing secrets** → Check **Settings → Secrets** for `LLM_API_KEY` and `GATEWAY_TOKEN`
+
+**Telegram not working** → Verify bot token is valid, check logs for `📱 Enabling Telegram`
+
+**Workspace not restoring** → Check `HF_USERNAME` and `HF_TOKEN` are set, token has write access
+
+**Space sleeping** → Check logs for `💓 Keep-alive started`. If missing, `SPACE_HOST` might not be set
+
+**"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
+
+---
+
+## 📚 Links
+
+- [OpenClaw Docs](https://docs.openclaw.ai) · [OpenClaw GitHub](https://github.com/openclaw/openclaw) · [HF Spaces Docs](https://huggingface.co/docs/hub/spaces)
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+Made with ❤️ by [@somratpro](https://github.com/somratpro) for the [OpenClaw](https://github.com/openclaw/openclaw) community

SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly:
+
+1. **Do NOT open a public issue**
+2. Email the maintainer or open a private security advisory on GitHub
+3. Include steps to reproduce if possible
+
+We'll respond within 48 hours and work on a fix.
+
+## Security Best Practices
+
+When deploying HuggingClaw:
+
+- **Set your Space to Private** — prevents unauthorized access to your gateway
+- **Use a strong `GATEWAY_TOKEN`** — generate with `openssl rand -hex 32`
+- **Keep your HF token scoped** — use fine-grained tokens with minimum permissions
+- **Don't commit `.env` files** — the `.gitignore` already excludes them
+- **Use `TELEGRAM_USER_ID`** — restricts bot access to your account only
+- **Review logs regularly** — check for unauthorized access attempts
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.0.x   | ✅        |

dns-fix.js

@@ -0,0 +1,19 @@
+// Fix HF Spaces DNS: internal resolver can't resolve discord.com / api.telegram.org
+// Override dns.lookup (used by http/https) to use Google/Cloudflare DNS
+const dns = require('dns');
+const { Resolver } = dns;
+const resolver = new Resolver();
+resolver.setServers(['8.8.8.8', '1.1.1.1']);
+
+const origLookup = dns.lookup;
+dns.lookup = function(hostname, options, callback) {
+  if (typeof options === 'function') { callback = options; options = { family: 0 }; }
+  resolver.resolve4(hostname, (err, addresses) => {
+    if (err || !addresses || !addresses.length) return origLookup.call(dns, hostname, options, callback);
+    if (options && options.all) {
+      callback(null, addresses.map(a => ({ address: a, family: 4 })));
+    } else {
+      callback(null, addresses[0], 4);
+    }
+  });
+};

health-server.js

@@ -0,0 +1,27 @@
+// Lightweight health endpoint on port 7861
+// OpenClaw runs on 7860, this runs alongside it
+// Returns 200 OK for keep-alive pings and external monitoring
+const http = require('http');
+
+const PORT = process.env.HEALTH_PORT || 7861;
+const startTime = Date.now();
+
+const server = http.createServer((req, res) => {
+  if (req.url === '/health' || req.url === '/') {
+    const uptime = Math.floor((Date.now() - startTime) / 1000);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      status: 'ok',
+      uptime: uptime,
+      uptimeHuman: `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m`,
+      timestamp: new Date().toISOString()
+    }));
+  } else {
+    res.writeHead(404);
+    res.end();
+  }
+});
+
+server.listen(PORT, '0.0.0.0', () => {
+  console.log(`🏥 Health server listening on port ${PORT}`);
+});

keep-alive.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Self-ping keep-alive for HF Spaces
+# HF Spaces sleeps after 48h of inactivity (no HTTP requests)
+# This script pings the Space's own URL to prevent that
+#
+# HF provides SPACE_HOST env var automatically (e.g., "username-spacename.hf.space")
+# Runs as a background process alongside the gateway
+
+INTERVAL="${KEEP_ALIVE_INTERVAL:-300}"  # Default: every 5 minutes
+
+if [ "$INTERVAL" = "0" ]; then
+  echo "⏸️  Keep-alive: disabled (KEEP_ALIVE_INTERVAL=0)"
+  exit 0
+fi
+
+if [ -z "$SPACE_HOST" ]; then
+  echo "⏸️  Keep-alive: SPACE_HOST not set (not on HF Spaces?), skipping."
+  exit 0
+fi
+
+# Ping the Space URL — any HTTP response (even 404) counts as activity
+PING_URL="https://${SPACE_HOST}"
+
+echo "💓 Keep-alive started: pinging ${PING_URL} every ${INTERVAL}s"
+
+while true; do
+  sleep "$INTERVAL"
+  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "$PING_URL" 2>/dev/null)
+  if [ "$HTTP_CODE" = "000" ]; then
+    echo "💓 Keep-alive: ping failed (network error), retrying next cycle..."
+  else
+    echo "💓 Keep-alive: OK"
+  fi
+done

start.sh

@@ -0,0 +1,330 @@
+#!/bin/bash
+set -e
+
+# ════════════════════════════════════════════════════════════════
+# HuggingClaw — OpenClaw Gateway for HF Spaces
+# ════════════════════════════════════════════════════════════════
+
+# ── Startup Banner ──
+OPENCLAW_VERSION="${OPENCLAW_VERSION:-latest}"
+echo ""
+echo "  ╔══════════════════════════════════════════╗"
+echo "  ║          🦞 HuggingClaw Gateway          ║"
+echo "  ╚══════════════════════════════════════════╝"
+echo ""
+
+# ── Validate required secrets ──
+ERRORS=""
+if [ -z "$LLM_API_KEY" ]; then
+  ERRORS="${ERRORS}  ❌ LLM_API_KEY is not set\n"
+fi
+if [ -z "$LLM_MODEL" ]; then
+  ERRORS="${ERRORS}  ❌ LLM_MODEL is not set (e.g. google/gemini-2.5-flash, anthropic/claude-sonnet-4-5, openai/gpt-4)\n"
+fi
+if [ -z "$GATEWAY_TOKEN" ]; then
+  ERRORS="${ERRORS}  ❌ GATEWAY_TOKEN is not set (generate: openssl rand -hex 32)\n"
+fi
+if [ -n "$ERRORS" ]; then
+  echo "Missing required secrets:"
+  echo -e "$ERRORS"
+  echo "Add them in HF Spaces → Settings → Secrets"
+  exit 1
+fi
+
+# ── Set LLM env based on model name ──
+
+# Auto-correct Gemini models to use google/ prefix if anthropic/ was mistakenly used
+if [[ "$LLM_MODEL" == "anthropic/gemini"* ]]; then
+  LLM_MODEL=$(echo "$LLM_MODEL" | sed 's/^anthropic\//google\//')
+  echo "⚠️  Corrected model from anthropic/gemini* to google/gemini*"
+fi
+
+# Extract provider prefix from model name (e.g. "google/gemini-2.5-flash" → "google")
+LLM_PROVIDER=$(echo "$LLM_MODEL" | cut -d'/' -f1)
+
+# Map provider prefix to the correct API key environment variable
+# Based on OpenClaw provider system: /usr/local/lib/node_modules/openclaw/docs/concepts/model-providers.md
+# Note: OpenClaw normalizes some prefixes (z-ai → zai, z.ai → zai, etc.)
+case "$LLM_PROVIDER" in
+  # ── Core Providers ──
+  anthropic)                    export ANTHROPIC_API_KEY="$LLM_API_KEY" ;;
+  openai|openai-codex)          export OPENAI_API_KEY="$LLM_API_KEY" ;;
+  google|google-vertex)         export GEMINI_API_KEY="$LLM_API_KEY" ;;
+  deepseek)                     export DEEPSEEK_API_KEY="$LLM_API_KEY" ;;
+  # ── OpenCode Providers ──
+  opencode)                     export OPENCODE_API_KEY="$LLM_API_KEY" ;;
+  opencode-go)                  export OPENCODE_API_KEY="$LLM_API_KEY" ;;
+  # ── Gateway/Router Providers ──
+  openrouter)                   export OPENROUTER_API_KEY="$LLM_API_KEY" ;;
+  kilocode)                     export KILOCODE_API_KEY="$LLM_API_KEY" ;;
+  vercel-ai-gateway)            export AI_GATEWAY_API_KEY="$LLM_API_KEY" ;;
+  # ── Chinese/Asian Providers ──
+  zai|z-ai|z.ai|zhipu)          export ZAI_API_KEY="$LLM_API_KEY" ;;
+  moonshot)                     export MOONSHOT_API_KEY="$LLM_API_KEY" ;;
+  kimi-coding)                  export KIMI_API_KEY="$LLM_API_KEY" ;;
+  minimax)                      export MINIMAX_API_KEY="$LLM_API_KEY" ;;
+  qwen|modelstudio)             export MODELSTUDIO_API_KEY="$LLM_API_KEY" ;;
+  xiaomi)                       export XIAOMI_API_KEY="$LLM_API_KEY" ;;
+  volcengine|volcengine-plan)   export VOLCANO_ENGINE_API_KEY="$LLM_API_KEY" ;;
+  byteplus|byteplus-plan)       export BYTEPLUS_API_KEY="$LLM_API_KEY" ;;
+  qianfan)                      export QIANFAN_API_KEY="$LLM_API_KEY" ;;
+  # ── Western Providers ──
+  mistral|mistralai)            export MISTRAL_API_KEY="$LLM_API_KEY" ;;
+  xai|x-ai)                    export XAI_API_KEY="$LLM_API_KEY" ;;
+  nvidia)                       export NVIDIA_API_KEY="$LLM_API_KEY" ;;
+  cohere)                       export COHERE_API_KEY="$LLM_API_KEY" ;;
+  groq)                         export GROQ_API_KEY="$LLM_API_KEY" ;;
+  together)                     export TOGETHER_API_KEY="$LLM_API_KEY" ;;
+  huggingface)                  export HUGGINGFACE_HUB_TOKEN="$LLM_API_KEY" ;;
+  cerebras)                     export CEREBRAS_API_KEY="$LLM_API_KEY" ;;
+  venice)                       export VENICE_API_KEY="$LLM_API_KEY" ;;
+  synthetic)                    export SYNTHETIC_API_KEY="$LLM_API_KEY" ;;
+  github-copilot)               export COPILOT_GITHUB_TOKEN="$LLM_API_KEY" ;;
+  # ── Fallback: Anthropic (default) ──
+  *)
+    export ANTHROPIC_API_KEY="$LLM_API_KEY"
+    ;;
+esac
+
+# ── Setup directories ──
+mkdir -p /home/node/.openclaw/agents/main/sessions
+mkdir -p /home/node/.openclaw/credentials
+mkdir -p /home/node/.openclaw/workspace
+chmod 700 /home/node/.openclaw
+chmod 700 /home/node/.openclaw/credentials
+
+# ── Validate HF token (if provided) ──
+if [ -n "$HF_TOKEN" ]; then
+  echo "🔑 Validating HF token..."
+  HF_AUTH_STATUS=$(curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $HF_TOKEN" https://huggingface.co/api/repos/create --max-time 10 2>/dev/null || echo "000")
+  if [ "$HF_AUTH_STATUS" = "401" ]; then
+    echo "  ⚠️  HF token is invalid or expired! Workspace backup will not work."
+    echo "  Get a new token: https://huggingface.co/settings/tokens"
+  else
+    echo "  ✅ HF token is valid"
+  fi
+fi
+
+# ── Auto-create + Restore workspace from HF Dataset ──
+if [ -n "$HF_USERNAME" ] && [ -n "$HF_TOKEN" ]; then
+  BACKUP_DATASET="${BACKUP_DATASET_NAME:-huggingclaw-backup}"
+  BACKUP_URL="https://${HF_USERNAME}:${HF_TOKEN}@huggingface.co/datasets/${HF_USERNAME}/${BACKUP_DATASET}"
+  
+  # Auto-create the dataset if it doesn't exist
+  echo "📦 Checking HF Dataset: ${HF_USERNAME}/${BACKUP_DATASET}..."
+  DATASET_CHECK=$(curl -s -o /dev/null -w "%{http_code}" \
+    -H "Authorization: Bearer $HF_TOKEN" \
+    "https://huggingface.co/api/datasets/${HF_USERNAME}/${BACKUP_DATASET}" \
+    --max-time 10 2>/dev/null || echo "000")
+  
+  if [ "$DATASET_CHECK" = "404" ]; then
+    echo "  📝 Dataset not found, creating ${HF_USERNAME}/${BACKUP_DATASET}..."
+    CREATE_RESULT=$(curl -s -w "\n%{http_code}" \
+      -X POST "https://huggingface.co/api/repos/create" \
+      -H "Authorization: Bearer $HF_TOKEN" \
+      -H "Content-Type: application/json" \
+      -d "{\"type\":\"dataset\",\"name\":\"${BACKUP_DATASET}\",\"private\":true}" \
+      --max-time 15 2>/dev/null || echo "error")
+    CREATE_STATUS=$(echo "$CREATE_RESULT" | tail -1)
+    if [ "$CREATE_STATUS" = "200" ] || [ "$CREATE_STATUS" = "201" ]; then
+      echo "  ✅ Dataset created: ${HF_USERNAME}/${BACKUP_DATASET} (private)"
+    else
+      echo "  ⚠️  Could not create dataset (HTTP $CREATE_STATUS). Create it manually:"
+      echo "     https://huggingface.co/datasets/create"
+    fi
+  elif [ "$DATASET_CHECK" = "200" ]; then
+    echo "  ✅ Dataset exists"
+  else
+    echo "  ⚠️  Could not check dataset (HTTP $DATASET_CHECK)"
+  fi
+  
+  # Restore workspace
+  echo "📦 Restoring workspace..."
+  WORKSPACE="/home/node/.openclaw/workspace"
+  GIT_USER_EMAIL="${WORKSPACE_GIT_USER:-openclaw@example.com}"
+  GIT_USER_NAME="${WORKSPACE_GIT_NAME:-OpenClaw Bot}"
+  
+  cd "$WORKSPACE"
+  if [ ! -d ".git" ]; then
+    git init -q
+    git remote add origin "$BACKUP_URL"
+  else
+    git remote set-url origin "$BACKUP_URL"
+  fi
+  
+  git config user.email "$GIT_USER_EMAIL"
+  git config user.name "$GIT_USER_NAME"
+  
+  if git fetch origin main 2>/dev/null; then
+    git reset --hard origin/main 2>/dev/null && echo "  ✅ Workspace restored!"
+  else
+    echo "  ⚠️ No remote data yet, starting fresh."
+  fi
+  cd /
+fi
+
+# ── Build config ──
+CONFIG_JSON=$(cat <<'CONFIGEOF'
+{
+  "gateway": {
+    "mode": "local",
+    "port": 7860,
+    "bind": "lan",
+    "auth": {
+      "token": ""
+    },
+    "controlUi": {
+      "allowInsecureAuth": true
+    },
+    "trustedProxies": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
+  },
+  "channels": {},
+  "plugins": {
+    "entries": {}
+  }
+}
+CONFIGEOF
+)
+
+# Gateway token
+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\"")
+
+# 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}\"]")
+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}')
+  export TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN"
+  
+  if [ -n "$TELEGRAM_USER_IDS" ]; then
+    # Convert comma-separated IDs to JSON array
+    IDS_JSON=$(echo "$TELEGRAM_USER_IDS" | tr ',' '\n' | sed 's/^ *//;s/ *$//' | jq -R . | jq -s .)
+    CONFIG_JSON=$(echo "$CONFIG_JSON" | jq ".channels.telegram = {\"dmPolicy\": \"allowlist\", \"allowFrom\": $IDS_JSON}")
+  elif [ -n "$TELEGRAM_USER_ID" ]; then
+    # Single user (backward compatible)
+    CONFIG_JSON=$(echo "$CONFIG_JSON" | jq ".channels.telegram = {\"dmPolicy\": \"allowlist\", \"allowFrom\": [\"$TELEGRAM_USER_ID\"]}")
+  fi
+fi
+
+# Write config
+echo "$CONFIG_JSON" > "/home/node/.openclaw/openclaw.json"
+chmod 600 /home/node/.openclaw/openclaw.json
+
+# ── Startup Summary ──
+echo ""
+echo "  ┌──────────────────────────────────────────┐"
+echo "  │  📋 Configuration Summary                │"
+echo "  ├──────────────────────────────────────────┤"
+printf "  │  %-40s │\n" "Model: $LLM_MODEL"
+if [ -n "$TELEGRAM_BOT_TOKEN" ]; then
+printf "  │  %-40s │\n" "Telegram: ✅ enabled"
+else
+printf "  │  %-40s │\n" "Telegram: ❌ not configured"
+fi
+if [ -n "$HF_USERNAME" ] && [ -n "$HF_TOKEN" ]; then
+printf "  │  %-40s │\n" "Backup: ✅ ${HF_USERNAME}/${BACKUP_DATASET:-huggingclaw-backup}"
+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}"
+else
+printf "  │  %-40s │\n" "Keep-alive: ⏸️  local mode"
+fi
+SYNC_STATUS="❌ disabled"
+if [ -n "$HF_USERNAME" ] && [ -n "$HF_TOKEN" ]; then
+  SYNC_STATUS="✅ every ${SYNC_INTERVAL:-600}s"
+fi
+printf "  │  %-40s │\n" "Auto-sync: $SYNC_STATUS"
+echo "  └──────────────────────────────────────────┘"
+echo ""
+
+# ── Trap SIGTERM for graceful shutdown ──
+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
+  fi
+  
+  # Kill background processes
+  kill $(jobs -p) 2>/dev/null
+  echo "👋 Goodbye!"
+  exit 0
+}
+trap graceful_shutdown SIGTERM SIGINT
+
+# ── Start background services ──
+node /home/node/app/health-server.js &
+/home/node/app/keep-alive.sh &
+
+python3 /home/node/app/workspace-sync.py &
+
+# ── Launch gateway ──
+echo "🚀 Launching OpenClaw gateway on port 7860..."
+echo ""
+# Set model via environment for the gateway
+export LLM_MODEL="$LLM_MODEL"
+
+
+
+openclaw gateway run --port 7860 --bind lan --verbose 2>&1 | tee -a /home/node/.openclaw/gateway.log &
+GATEWAY_PID=$!
+
+# Wait a moment for startup errors
+sleep 3
+if ! kill -0 $GATEWAY_PID 2>/dev/null; then
+  echo ""
+  echo "❌ Gateway failed to start. Last 30 lines of log:"
+  echo "────────────────────────────────────────────"
+  tail -30 /home/node/.openclaw/gateway.log
+  exit 1
+fi
+
+# Wait for gateway (allows trap to fire)
+wait $GATEWAY_PID

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()