Kpd81/HuggingClaw

<div align="center"> <img src="HuggingClaw.png" alt="HuggingClaw" width="720"/> <br/><br/> <strong>The best way to deploy <a href="https://github.com/openclaw/openclaw">OpenClaw</a> on the cloud</strong> <br/> _{Zero hardware · Always online · Auto-persistent · One-click deploy} <br/><br/>

         </div>

Why HuggingClaw?

OpenClaw is a powerful, popular AI assistant (Telegram, WhatsApp, 40+ channels), but it’s meant to run on your own machine (e.g. a Mac Mini). Not everyone has that. You can deploy on the cloud, but most providers either charge by the hour or offer only very limited resources. HuggingFace Spaces gives you 2 vCPU and 16 GB RAM for free — a good fit for OpenClaw, but Spaces have two problems we fix.

HuggingClaw is this repo. It fixes two Hugging Face Space issues: (1) Data is not persistent — we use a private HuggingFace Dataset to sync and restore your conversations, settings, and credentials so they survive restarts; (2) DNS resolution fails for some domains (e.g. WhatsApp) — we fix it with DNS-over-HTTPS and a Node.js DNS patch so OpenClaw can connect reliably.

Architecture

<div align="center"> <img src="assets/architecture.svg" alt="Architecture" width="720"/> </div>

Quick Start

1. Duplicate this Space

Click Duplicate this Space on the HuggingClaw Space page.

After duplicating: Edit your Space's README.md and update the datasets: field in the YAML header to point to your own dataset repo (e.g. your-name/YourSpace-data), or remove it entirely. This prevents your Space from appearing as linked to the original dataset.

2. Set Secrets

Go to Settings → Repository secrets and configure:

Data Persistence

HuggingClaw syncs ~/.openclaw (conversations, settings, credentials) to a private HuggingFace Dataset repo so data survives restarts. There are two ways to set this up:

Option A — Manual mode (default, recommended)

1. 1.Go to huggingface.co/new-dataset and create a private Dataset repo (e.g. your-name/HuggingClaw-data)
2. 2.Set OPENCLAW_DATASET_REPO = your-name/HuggingClaw-data in your Space secrets
3. 3.Set HF_TOKEN with write permission
4. 4.Done — HuggingClaw will sync to this repo every 60 seconds

Option B — Auto mode

1. 1.Set AUTO_CREATE_DATASET = true in your Space secrets
2. 2.Set HF_TOKEN with write permission
3. 3.(Optional) Set OPENCLAW_DATASET_REPO if you want a custom repo name
4. 4.On first startup, HuggingClaw automatically creates a private Dataset repo. If OPENCLAW_DATASET_REPO is not set, it derives the name from your HF username + Space name: your-username/SpaceName-data (e.g. your-name/YourSpace-data). Each Space gets its own dataset, so duplicating a Space won't cause conflicts

Security note: AUTO_CREATE_DATASET defaults to false — the system will not create repos on your behalf unless you explicitly opt in.

Environment Variables

Fine-tune persistence and performance. Set these as Repository Secrets in HF Spaces, or in .env for local Docker.

For the full list (including OPENAI_BASE_URL, OLLAMA_HOST, proxy settings, etc.), see `.env.example`.

3. Open the Control UI

Visit your Space URL. Enter the gateway token (default: huggingclaw) to connect. Customize via GATEWAY_TOKEN secret.

Messaging integrations (Telegram, WhatsApp) can be configured directly inside the Control UI after connecting.

Telegram note: HF Spaces blocks api.telegram.org DNS. HuggingClaw automatically probes alternative API endpoints at startup and selects one that works — no manual configuration needed.

Configuration

HuggingClaw supports all OpenClaw environment variables — it passes the entire environment to the OpenClaw process (env=os.environ.copy()), so any variable from the OpenClaw docs works out of the box in HF Spaces. This includes:

• —API Keys — OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, MISTRAL_API_KEY, COHERE_API_KEY, OPENROUTER_API_KEY
• —Server — OPENCLAW_API_PORT, OPENCLAW_WS_PORT, OPENCLAW_HOST
• —Memory — OPENCLAW_MEMORY_BACKEND, OPENCLAW_REDIS_URL, OPENCLAW_SQLITE_PATH
• —Network — OPENCLAW_HTTP_PROXY, OPENCLAW_HTTPS_PROXY, OPENCLAW_NO_PROXY
• —Ollama — OLLAMA_HOST, OLLAMA_NUM_PARALLEL, OLLAMA_KEEP_ALIVE
• —Secrets — OPENCLAW_SECRETS_BACKEND, VAULT_ADDR, VAULT_TOKEN

HuggingClaw adds its own variables for persistence and deployment: HF_TOKEN, OPENCLAW_DATASET_REPO, AUTO_CREATE_DATASET, SYNC_INTERVAL, OPENCLAW_DEFAULT_MODEL, etc. See `.env.example` for the complete reference.

Security

• —Token authentication — Control UI requires a gateway token to connect (default: huggingclaw, customizable via GATEWAY_TOKEN)
• —Secrets stay server-side — API keys and tokens are never exposed to the browser
• —Private backups — the Dataset repo is created as private by default

License

MIT