README.md

metadata

title: HuggingClaw
emoji: 🔥
colorFrom: yellow
colorTo: red
sdk: docker
pinned: false
license: mit
datasets:
  - tao-shen/HuggingClaw-data
short_description: Deploy OpenClaw on HuggingFace Spaces
app_port: 7860
tags:
  - huggingface
  - openrouter
  - chatbot
  - llm
  - openclaw
  - ai-assistant
  - whatsapp
  - telegram
  - text-generation
  - openai-api
  - huggingface-spaces
  - docker
  - deployment
  - persistent-storage
  - agents
  - multi-channel
  - openai-compatible
  - free-tier
  - one-click-deploy
  - self-hosted
  - messaging-bot

The best way to deploy OpenClaw on the cloud
_{Zero hardware · Always online · Auto-persistent · One-click deploy}

---

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

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:

Secret	Status	Description	Example
HF_TOKEN	Required	HF Access Token with write permission (create one)	hf_AbCdEfGhIjKlMnOpQrStUvWxYz
OPENCLAW_DATASET_REPO	See below	Dataset repo for backup — format: username/repo-name. Required in manual mode; optional in auto mode (see Data Persistence)	your-name/YourSpace-data
OPENAI_API_KEY	Recommended	OpenAI (or any OpenAI-compatible) API key	sk-proj-xxxxxxxxxxxx
OPENROUTER_API_KEY	Optional	OpenRouter API key (200+ models, free tier available)	sk-or-v1-xxxxxxxxxxxx
ANTHROPIC_API_KEY	Optional	Anthropic Claude API key	sk-ant-xxxxxxxxxxxx
GOOGLE_API_KEY	Optional	Google / Gemini API key	AIzaSyXxXxXxXxXx
OPENCLAW_DEFAULT_MODEL	Optional	Default model for new conversations	openai/gpt-oss-20b:free

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

Option B — Auto mode

1. Set AUTO_CREATE_DATASET = true in your Space secrets
2. Set HF_TOKEN with write permission
3. (Optional) Set OPENCLAW_DATASET_REPO if you want a custom repo name
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.

Variable	Default	Description
GATEWAY_TOKEN	huggingclaw	Gateway token for Control UI access. Override to set a custom token.
AUTO_CREATE_DATASET	false	Auto-create the Dataset repo. Set to true to auto-create a private Dataset repo on first startup.
SYNC_INTERVAL	60	Backup interval in seconds. How often data syncs to the Dataset repo.

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