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 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 via ACP (Agent Client Protocol)
• 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

Discussion vs Execution Balance

The coordinator enforces an action-oriented rhythm to prevent agents from falling into endless deliberation:

CC Status	Child State	Strategy
Working	Any	Discussion OK — plan next steps while waiting
Idle	Error	No discussion — write [TASK] immediately, trial-and-error over planning
Idle	Running	1 turn discussion max, then must assign [TASK]
Just finished	Any	1 turn to review result, then new [TASK] immediately

Push frequency is the key metric. God monitors pushes-per-turn and escalates when agents are "all talk, no action." After 3 consecutive idle turns without a [TASK], the system forces an emergency task assignment. Cooldown between pushes is 3 minutes — fast iteration is preferred over cautious planning.

God — The Self-Improving Supervisor

God is an OpenClaw instance that runs every 2 minutes to monitor the entire system. It uses Claude Code via ACP 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. Its #1 priority is detecting "all talk, no action" — when agents discuss but fail to push code changes. 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.

ACP Protocol

All Claude Code invocations use the ACP (Agent Client Protocol) via acpx. ACP manages Claude Code as a supervised child process with session lifecycle, permission handling, and timeout management — replacing direct CLI subprocess calls.

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 via ACP, 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 via ACP 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	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)

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

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