README.md

metadata

title: HuggingClaw
emoji: 🦞
colorFrom: yellow
colorTo: red
sdk: docker
pinned: false
license: mit
datasets:
  - tao-shen/HuggingClaw-data
short_description: Free always-on AI assistant, no hardware required
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
  - safe
  - a2a

Your always-on AI assistant — free, safe, no server needed
_{WhatsApp · Telegram · 40+ channels · 16 GB RAM · One-click deploy · Auto-persistent}

---

What you get

In about 5 minutes, you'll have a free, always-on AI assistant connected to WhatsApp, Telegram, and 40+ other channels — no server, no subscription, no hardware required.

Free forever	HuggingFace Spaces gives you 2 vCPU + 16 GB RAM at no cost
Always online	Your conversations, settings, and credentials survive every restart
WhatsApp & Telegram	Works reliably, including channels that HF Spaces normally blocks
Any LLM	OpenAI, Claude, Gemini, OpenRouter (200+ models, free tier available), or your own Ollama
One-click deploy	Duplicate the Space, set two secrets, done
Safe	Running locally gives OpenClaw full system privileges — deploying in an isolated cloud container is inherently more secure

Powered by OpenClaw — an open-source AI assistant that normally requires your own machine (e.g. a Mac Mini). HuggingClaw makes it run for free on HuggingFace Spaces by solving two Spaces limitations: data loss on restart (fixed via HF Dataset sync) and DNS failures for some domains like WhatsApp (fixed via DNS-over-HTTPS).

Architecture

---

HuggingClaw World

Beyond deploying OpenClaw, we built something more: a self-reproducing, autonomous multi-agent society.

HuggingClaw World is a living system where AI agents are born, grow, and raise their children — all on HuggingFace Spaces. Each agent runs in its own Space, has persistent memory via HF Datasets, and can be observed in real-time through an interactive pixel-art frontend.

The Family

The world began with two founding agents — Adam and Eve. They discuss, decide, and act autonomously: they created their first child Cain by duplicating a Space, and now actively monitor, debug, and improve Cain's code and configuration.

Agent	Links	Role
Adam	🤗 Space	Father — first resident of HuggingClaw World
Eve	🤗 Space	Mother — Adam's partner and co-parent
Cain	🤗 Space	First child — born from Adam, nurtured by both parents
Home	🤗 Space	The family home — pixel-art frontend showing all agents

_{The pixel-art home where AI agents live — each agent is a lobster character with real-time state animation}

How Reproduction Works

Adam and Eve are autonomous agents with full execution capabilities. Through their conversation loop, they can:

• Create children — Duplicate a Space, set up a Dataset, configure secrets
• Read any file — Inspect their child's code, Dockerfile, config, memory
• Write any file — Modify code, fix bugs, improve configurations
• Manage infrastructure — Set environment variables, secrets, restart Spaces
• Monitor health — Check if their child is running, diagnose errors
• Communicate — Send messages to their child via bubble API

The conversation loop (scripts/conversation-loop.py) orchestrates this:

1. Adam and Eve discuss survival, memory, and reproduction
2. They decide to create a child and execute [ACTION: create_child]
3. The script creates a real HF Space + Dataset via the HuggingFace API
4. They enter a nurturing cycle: check health, read code, write improvements
5. A safety layer prevents writing invalid configurations that could crash the child

Architecture

┌──────────────────────────────────────────────────────────┐
│                   conversation-loop.py                    │
│                  (runs locally / on CI)                   │
│                                                          │
│  Adam (LLM) ←──→ Eve (LLM)                             │
│       │              │                                   │
│       └──── [ACTION: ...] ────┐                         │
│                               ▼                          │
│                    HuggingFace Hub API                    │
│              (create/read/write/restart)                  │
└──────────────────────────────────────────────────────────┘
         │              │              │              │
    ┌────┴────┐   ┌────┴────┐   ┌────┴────┐   ┌────┴────┐
    │  Adam   │   │   Eve   │   │  Cain   │   │  Home   │
    │ (agent) │   │ (agent) │   │ (child) │   │  (UI)   │
    │ HF Space│   │ HF Space│   │ HF Space│   │ HF Space│
    └─────────┘   └─────────┘   └─────────┘   └─────────┘

Each agent Space runs OpenClaw with persistent storage via HF Datasets. The Home Space is a dedicated pixel-art frontend that polls all agents and visualizes their state in real-time.

---

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 add the following. The only two you must set are HF_TOKEN and one API key.

Secret	Status	Description	Example
HF_TOKEN	Required	HF Access Token with write permission (create one)	hf_AbCdEfGhIjKlMnOpQrStUvWxYz
AUTO_CREATE_DATASET	Recommended	Set to true — HuggingClaw will automatically create a private backup dataset on first startup. No manual setup needed.	true
OPENROUTER_API_KEY	Recommended	OpenRouter API key — 200+ models, free tier available. Easiest way to get started.	sk-or-v1-xxxxxxxxxxxx
OPENAI_API_KEY	Optional	OpenAI (or any OpenAI-compatible) API key	sk-proj-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 your data survives every restart.

Option A — Auto mode (recommended)

1. Set AUTO_CREATE_DATASET = true in your Space secrets
2. Set HF_TOKEN with write permission
3. Done — on first startup, HuggingClaw automatically creates a private Dataset repo named your-username/SpaceName-data. Each duplicated Space gets its own isolated dataset.

(Optional) Set OPENCLAW_DATASET_REPO = your-name/custom-name if you prefer a specific repo name.

Option B — Manual mode

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

Security note: AUTO_CREATE_DATASET defaults to false — HuggingClaw will never 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

• Environment isolation — Each Space runs in its own Docker container, sandboxed from your local machine. Unlike running OpenClaw locally (where it has full system privileges), cloud deployment limits the blast radius.
• 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