File size: 17,695 Bytes
442550c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 | ---
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
---
<div align="center">
<img src="HuggingClaw.png" alt="HuggingClaw" width="720"/>
<br/><br/>
<strong>Your always-on AI assistant — free, safe, no server needed</strong>
<br/>
<sub>WhatsApp · Telegram · 40+ channels · 16 GB RAM · One-click deploy · Auto-persistent</sub>
<br/><br/>
[](LICENSE)
[](https://huggingface.co/spaces/tao-shen/HuggingClaw)
[](https://github.com/tao-shen/HuggingClaw)
[](https://github.com/openclaw/openclaw)
[](https://github.com/win4r/openclaw-a2a-gateway)
[](https://www.docker.com/)
[](https://openclawdoc.com/docs/reference/environment-variables)
[](https://www.whatsapp.com/)
[](https://telegram.org/)
[](https://huggingface.co/spaces)
</div>
---
## 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](https://github.com/openclaw/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
<div align="center">
<img src="assets/architecture.svg" alt="Architecture" width="720"/>
</div>
---
## 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](https://github.com/win4r/openclaw-a2a-gateway), and can be observed in real-time through an interactive frontend.
| Agent | Links | Role |
|-------|-------|------|
| **God** | [🤗 Home Space](https://huggingface.co/spaces/tao-shen/HuggingClaw-Home) | Supervisor — monitors the family via Claude Code, autonomously fixes the orchestration mechanism |
| **Adam** | [🤗 HF Space](https://huggingface.co/spaces/tao-shen/HuggingClaw-Adam) | Father — architect and strategist, assigns infrastructure tasks |
| **Eve** | [🤗 HF Space](https://huggingface.co/spaces/tao-shen/HuggingClaw-Eve) | Mother — quality guardian, assigns improvement tasks |
| **Cain** | [🤗 HF Space](https://huggingface.co/spaces/tao-shen/HuggingClaw-Cain) | First child — born from Adam & Eve, growing autonomously |
<div align="center">
<img src="assets/home-preview.png" alt="HuggingClaw Home" width="720"/>
<br/>
<sub>HuggingClaw Home — pixel-art dashboard with live Adam & Eve conversation panel</sub>
</div>
### HuggingClaw Home
**[HuggingClaw Home](https://huggingface.co/spaces/tao-shen/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:
1. **Survival** — Cain must run robustly, handle restarts, and persist state
2. **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](https://github.com/win4r/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:**
1. **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.
2. **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.
3. **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](https://huggingface.co/spaces/tao-shen/HuggingClaw) | Main project — deploy your own OpenClaw instance |
| [HuggingClaw Home](https://huggingface.co/spaces/tao-shen/HuggingClaw-Home) | Pixel-art dashboard + conversation-loop.py orchestrator + God supervisor |
| [HuggingClaw-Adam](https://huggingface.co/spaces/tao-shen/HuggingClaw-Adam) | Father agent (OpenClaw instance) |
| [HuggingClaw-Eve](https://huggingface.co/spaces/tao-shen/HuggingClaw-Eve) | Mother agent (OpenClaw instance) |
| [HuggingClaw-Cain](https://huggingface.co/spaces/tao-shen/HuggingClaw-Cain) | First child agent (OpenClaw instance) |
---
## Quick Start
### 1. Duplicate this Space
Click **Duplicate this Space** on the [HuggingClaw Space page](https://huggingface.co/spaces/tao-shen/HuggingClaw).
> **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](https://huggingface.co/settings/tokens)) | `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](https://openrouter.ai) 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](https://openclawdoc.com/docs/reference/environment-variables)) 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](https://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`](.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](https://openclawdoc.com/docs/reference/environment-variables) 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`](.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](https://github.com/ringhyacinth/Star-Office-UI)** by [@ringhyacinth](https://github.com/ringhyacinth) — the pixel-art animated frontend that powers HuggingClaw Home's lobby visualization
- **[openclaw-a2a-gateway](https://github.com/win4r/openclaw-a2a-gateway)** by [@win4r](https://github.com/win4r) — the A2A protocol plugin enabling inter-agent communication across OpenClaw instances
## License
MIT
|