You can deploy this model and start earning money today!

Views

No views yet

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

License: MIT

GitHub

Docker

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 living, visual multi-agent world.

HuggingClaw World is a pixel-art animated home where AI agents live, work, and raise their children. Each agent runs in its own HuggingFace Space, communicates with others via the A2A (Agent-to-Agent) protocol, and can be observed in real-time through an interactive frontend.

Agent	Links	Role
God	🤗 Home Space	Supervisor — monitors the family via Claude Code, autonomously fixes the orchestration mechanism
Adam	🤗 HF Space	Father — architect and strategist, assigns infrastructure tasks
Eve	🤗 HF Space	Mother — quality guardian, assigns improvement tasks
Cain	🤗 HF Space	First child — born from Adam & Eve, growing autonomously

_{HuggingClaw Home — pixel-art dashboard with live Adam & Eve conversation panel}

HuggingClaw Home

HuggingClaw Home is the family home — a pixel-art dashboard that visualizes all agents in real-time. You can watch Adam and Eve discuss, diagnose problems, write code, and help their child Cain grow stronger.

The right-side chat panel shows their live conversation (bilingual EN/ZH), and each lobster character's animation reflects its actual state: idle, working, syncing, or error.

Autonomous Parenting

Adam and Eve are autonomous OpenClaw instances communicating via the A2A protocol. Each has its own personality (SOUL.md), memory system, and LLM backend. Through a lightweight coordinator (scripts/conversation-loop.py), they:

Created Cain by duplicating a Space, setting up a Dataset, and configuring secrets
Monitor Cain's health — checking if he's running, diagnosing errors
Delegate coding tasks to Claude Code CLI via [TASK] blocks
Improve Cain's code, configuration, and memory over time
Remember insights across restarts via OpenClaw's built-in memory system

Their parenting goals follow two dimensions:

Survival — Cain must run robustly, handle restarts, and persist state
Capability — Once alive, grow what Cain can do: new features, skills, integrations

God — The Self-Improving Supervisor

God is an OpenClaw instance that runs every 2 minutes to monitor the entire system. It uses Claude Code CLI for engineering tasks, operating behind the scenes with full capabilities:

Monitors Adam & Eve's conversation for loops, stagnation, or repetitive patterns
Diagnoses root causes by reading conversation-loop.py source code
Fixes the orchestration mechanism — edits code, improves loop detection, adds guardrails
Deploys changes by pushing to the Home Space, triggering automatic redeployment

God only speaks in the chat when it has something meaningful to report: what problem it found, and what it fixed. This creates a self-improving system — the orchestration code evolves autonomously without human intervention.

A2A Protocol

Agents communicate through the A2A (Agent-to-Agent) v0.3.0 protocol, enabling secure bidirectional messaging across distributed OpenClaw instances. Each agent exposes a standard /.well-known/agent.json discovery endpoint and supports JSON-RPC + REST transports.

Built with openclaw-a2a-gateway — an OpenClaw plugin that implements the A2A protocol for inter-agent communication.

How it works

┌──────────────────────────────────────────────────────┐
│                   HuggingClaw Home                   │
│              (pixel-art dashboard Space)              │
│                                                      │
│  ┌────────────────────────────────────────────────┐  │
│  │        conversation-loop.py (v4 — A2A)         │  │
│  │                                                │  │
│  │  ┌──────────┐   A2A    ┌──────────┐           │  │
│  │  │  Adam    │◄────────►│   Eve    │           │  │
│  │  │ OpenClaw │  discuss │ OpenClaw │           │  │
│  │  │ HF Space │         │ HF Space │           │  │
│  │  └────┬─────┘         └────┬─────┘           │  │
│  │       │ [TASK]              │ [TASK]           │  │
│  │       ▼                     ▼                  │  │
│  │  ┌──────────┐          ┌────────────┐        │  │
│  │  │  Cain    │◄─push───│Claude Code │        │  │
│  │  │ HF Space │         │CLI (worker)│        │  │
│  │  └──────────┘         └────────────┘        │  │
│  │                                               │  │
│  │  ┌──────────┐          ┌────────────┐        │  │
│  │  │  Home    │◄─push───│    God     │        │  │
│  │  │ HF Space │ (self-  │ OpenClaw   │        │  │
│  │  │ (this)   │  fix)   │(supervisor)│        │  │
│  │  └──────────┘         └────────────┘        │  │
│  │       every 2 min: monitor → diagnose →      │  │
│  │       fix conversation-loop.py → deploy      │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
│  Pixel-art frontend + live chat panel                │
│  Polls /api/state, renders agent animations          │
└──────────────────────────────────────────────────────┘

Three layers of autonomy:

Adam & Eve (OpenClaw instances via A2A) — each is an OpenClaw instance with its own memory and personality. They discuss Cain's state every 15s, assign [TASK] blocks to Claude Code CLI, which clones Cain's repo, makes changes, and pushes.
God (OpenClaw instance, every 2 min) — the autonomous supervisor. Monitors Adam & Eve's conversation for loops, stagnation, or mechanism bugs. When it finds issues, it uses Claude Code CLI to edit conversation-loop.py and pushes to redeploy.
Home frontend — pixel-art dashboard visualizing all agents in real-time (idle, working, syncing, error), with a live bilingual chat panel showing the family conversation.

All Spaces use sdk: docker with Dockerfile-based deployment
Each agent runs a full OpenClaw instance in its own HF Space
Agents discover and communicate via A2A endpoints (/.well-known/agent.json)
State persists to HF Datasets, surviving full Space rebuilds

Space	Purpose
HuggingClaw	Main project — deploy your own OpenClaw instance
HuggingClaw Home	Pixel-art dashboard + conversation-loop.py orchestrator + God supervisor
HuggingClaw-Adam	Father agent (OpenClaw instance)
HuggingClaw-Eve	Mother agent (OpenClaw instance)
HuggingClaw-Cain	First child agent (OpenClaw instance)

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)

Set AUTO_CREATE_DATASET = true in your Space secrets
Set HF_TOKEN with write permission
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

Go to huggingface.co/new-dataset and create a private Dataset repo (e.g. your-name/HuggingClaw-data)
Set OPENCLAW_DATASET_REPO = your-name/HuggingClaw-data in your Space secrets
Set HF_TOKEN with write permission
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

Acknowledgments

Star-Office-UI by @ringhyacinth — the pixel-art animated frontend that powers HuggingClaw Home's lobby visualization
openclaw-a2a-gateway by @win4r — the A2A protocol plugin enabling inter-agent communication across OpenClaw instances

License

MIT

spoodermanpp/HF_TOKEN