ckriti/HuggingClaw
0
1---2title: HuggingClaw3emoji: 🔥4colorFrom: yellow5colorTo: red6sdk: docker7pinned: false8license: mit9datasets:10 - tao-shen/HuggingClaw-data11short_description: Deploy OpenClaw on HuggingFace Spaces12app_port: 786013tags:14 - huggingface15 - openrouter16 - chatbot17 - llm18 - openclaw19 - ai-assistant20 - whatsapp21 - telegram22 - text-generation23 - openai-api24 - huggingface-spaces25 - docker26 - deployment27 - persistent-storage28 - agents29 - multi-channel30 - openai-compatible31 - free-tier32 - one-click-deploy33 - self-hosted34 - messaging-bot35---36 37<div align="center">38 <img src="HuggingClaw.png" alt="HuggingClaw" width="720"/>39 <br/><br/>40 <strong>The best way to deploy <a href="https://github.com/openclaw/openclaw">OpenClaw</a> on the cloud</strong>41 <br/>42 <sub>Zero hardware · Always online · Auto-persistent · One-click deploy</sub>43 <br/><br/>44 45 [](LICENSE)46 [](https://huggingface.co)47 [](https://huggingface.co/spaces/tao-shen/HuggingClaw)48 [](https://github.com/openclaw/openclaw)49 [](https://www.docker.com/)50 [](https://openclawdoc.com/docs/reference/environment-variables)51 [](https://www.whatsapp.com/)52 [](https://telegram.org/)53 [](https://huggingface.co/spaces)54</div>55 56---57 58## Why HuggingClaw?59 60[OpenClaw](https://github.com/openclaw/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.61 62**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.63 64## Architecture65 66<div align="center">67 <img src="assets/architecture.svg" alt="Architecture" width="720"/>68</div>69 70## Quick Start71 72### 1. Duplicate this Space73 74Click **Duplicate this Space** on the [HuggingClaw Space page](https://huggingface.co/spaces/tao-shen/HuggingClaw).75 76> **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.77 78### 2. Set Secrets79 80Go to **Settings → Repository secrets** and configure:81 82| Secret | Status | Description | Example |83|--------|:------:|-------------|---------|84| `HF_TOKEN` | **Required** | HF Access Token with write permission ([create one](https://huggingface.co/settings/tokens)) | `hf_AbCdEfGhIjKlMnOpQrStUvWxYz` |85| `OPENCLAW_DATASET_REPO` | See below | Dataset repo for backup — format: `username/repo-name`. Required in manual mode; optional in auto mode (see [Data Persistence](#data-persistence)) | `your-name/YourSpace-data` |86| `OPENAI_API_KEY` | Recommended | OpenAI (or any [OpenAI-compatible](https://openclawdoc.com/docs/reference/environment-variables)) API key | `sk-proj-xxxxxxxxxxxx` |87| `OPENROUTER_API_KEY` | Optional | [OpenRouter](https://openrouter.ai) API key (200+ models, free tier available) | `sk-or-v1-xxxxxxxxxxxx` |88| `ANTHROPIC_API_KEY` | Optional | Anthropic Claude API key | `sk-ant-xxxxxxxxxxxx` |89| `GOOGLE_API_KEY` | Optional | Google / Gemini API key | `AIzaSyXxXxXxXxXx` |90| `OPENCLAW_DEFAULT_MODEL` | Optional | Default model for new conversations | `openai/gpt-oss-20b:free` |91 92### Data Persistence93 94HuggingClaw syncs `~/.openclaw` (conversations, settings, credentials) to a private HuggingFace Dataset repo so data survives restarts. There are two ways to set this up:95 96**Option A — Manual mode (default, recommended)**97 981. Go to [huggingface.co/new-dataset](https://huggingface.co/new-dataset) and create a **private** Dataset repo (e.g. `your-name/HuggingClaw-data`)992. Set `OPENCLAW_DATASET_REPO` = `your-name/HuggingClaw-data` in your Space secrets1003. Set `HF_TOKEN` with write permission1014. Done — HuggingClaw will sync to this repo every 60 seconds102 103**Option B — Auto mode**104 1051. Set `AUTO_CREATE_DATASET` = `true` in your Space secrets1062. Set `HF_TOKEN` with write permission1073. (Optional) Set `OPENCLAW_DATASET_REPO` if you want a custom repo name1084. 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 conflicts109 110> **Security note:** `AUTO_CREATE_DATASET` defaults to `false` — the system will not create repos on your behalf unless you explicitly opt in.111 112### Environment Variables113 114Fine-tune persistence and performance. Set these as **Repository Secrets** in HF Spaces, or in `.env` for local Docker.115 116| Variable | Default | Description |117|----------|---------|-------------|118| `GATEWAY_TOKEN` | `huggingclaw` | **Gateway token for Control UI access.** Override to set a custom token. |119| `AUTO_CREATE_DATASET` | `false` | **Auto-create the Dataset repo.** Set to `true` to auto-create a private Dataset repo on first startup. |120| `SYNC_INTERVAL` | `60` | **Backup interval in seconds.** How often data syncs to the Dataset repo. |121 122> For the full list (including `OPENAI_BASE_URL`, `OLLAMA_HOST`, proxy settings, etc.), see [`.env.example`](.env.example).123 124### 3. Open the Control UI125 126Visit your Space URL. Enter the gateway token (default: `huggingclaw`) to connect. Customize via `GATEWAY_TOKEN` secret.127 128Messaging integrations (Telegram, WhatsApp) can be configured directly inside the Control UI after connecting.129 130> **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.131 132## Configuration133 134HuggingClaw 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](https://openclawdoc.com/docs/reference/environment-variables) works out of the box in HF Spaces. This includes:135 136- **API Keys** — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `MISTRAL_API_KEY`, `COHERE_API_KEY`, `OPENROUTER_API_KEY`137- **Server** — `OPENCLAW_API_PORT`, `OPENCLAW_WS_PORT`, `OPENCLAW_HOST`138- **Memory** — `OPENCLAW_MEMORY_BACKEND`, `OPENCLAW_REDIS_URL`, `OPENCLAW_SQLITE_PATH`139- **Network** — `OPENCLAW_HTTP_PROXY`, `OPENCLAW_HTTPS_PROXY`, `OPENCLAW_NO_PROXY`140- **Ollama** — `OLLAMA_HOST`, `OLLAMA_NUM_PARALLEL`, `OLLAMA_KEEP_ALIVE`141- **Secrets** — `OPENCLAW_SECRETS_BACKEND`, `VAULT_ADDR`, `VAULT_TOKEN`142 143HuggingClaw 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`](.env.example) for the complete reference.144 145## Security146 147- **Token authentication** — Control UI requires a gateway token to connect (default: `huggingclaw`, customizable via `GATEWAY_TOKEN`)148- **Secrets stay server-side** — API keys and tokens are never exposed to the browser149- **Private backups** — the Dataset repo is created as private by default150 151## License152 153MIT154