Hugging Face's logo

Spaces:
micas23
/
codeclaw-backup
Sleeping

App Files Community
codeclaw-backup / README.md
somratpro
Make LLM_MODEL required + add Duplicate Space button
cfe4b3a
preview code
|
raw
history blame
8.74 kB
metadata 
title: HuggingClaw
emoji: 🦞
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: true

GitHub Stars License: MIT HF Space OpenClaw

🦞 HuggingClaw

Run your own always-on AI assistant on HuggingFace Spaces — for free.

Works with any LLM (Anthropic, OpenAI, Google), connects via Telegram, and persists your workspace to HF Datasets automatically.

✨ Features

  • Zero-config — just add 3 secrets and deploy
  • Any LLM provider — Claude, GPT-4, Gemini, etc.
  • Built-in keep-alive — self-pings to prevent HF sleep (no external cron needed)
  • Auto-sync workspace — commits + pushes changes every 10 min
  • Auto-create backup — creates the HF Dataset for you if it doesn't exist
  • Graceful shutdown — saves workspace before container dies
  • Multi-user Telegram — supports comma-separated user IDs for teams
  • Health endpoint — /health for monitoring
  • Version pinning — lock OpenClaw to a specific version
  • 100% HF-native — runs entirely on HuggingFace infrastructure

🚀 Quick Start

1. Duplicate this Space

Duplicate this Space

Click the button above → name it → set to Private

2. Add Required Secrets

Go to Settings → Secrets:

Secret Value
LLM_API_KEY Your API key (Anthropic / OpenAI / Google)
LLM_MODEL Model to use (e.g. google/gemini-2.5-flash, anthropic/claude-sonnet-4-5, openai/gpt-4)
GATEWAY_TOKEN Run openssl rand -hex 32 to generate

3. Deploy

That's it! The Space builds and starts automatically.

4. (Optional) Add Telegram

Secret Value
TELEGRAM_BOT_TOKEN From @BotFather
TELEGRAM_USER_ID Your user ID (how to find)

5. (Optional) Enable Workspace Backup

Secret Value
HF_USERNAME Your HuggingFace username
HF_TOKEN HF token with write access

The backup dataset (huggingclaw-backup) is created automatically — no manual setup needed.

📋 All Configuration Options

See .env.example for the complete reference with examples.

Required

Variable Purpose
LLM_API_KEY LLM provider API key
LLM_MODEL Model to use (e.g. google/gemini-2.5-flash, anthropic/claude-sonnet-4-5, openai/gpt-4) — auto-detects provider from prefix
GATEWAY_TOKEN Gateway auth token

Telegram

Variable Purpose
TELEGRAM_BOT_TOKEN Bot token from @BotFather
TELEGRAM_USER_ID Single user allowlist
TELEGRAM_USER_IDS Multiple users (comma-separated): 123,456,789

Workspace Backup

Variable Default Purpose
HF_USERNAME — Your HF username
HF_TOKEN — HF token (write access)
BACKUP_DATASET_NAME huggingclaw-backup Dataset name (auto-created!)
WORKSPACE_GIT_USER openclaw@example.com Git commit email
WORKSPACE_GIT_NAME OpenClaw Bot Git commit name

Background Services

Variable Default Purpose
KEEP_ALIVE_INTERVAL 300 (5 min) Self-ping interval. 0 = disable
SYNC_INTERVAL 600 (10 min) Auto-sync interval

Advanced

Variable Default Purpose
OPENCLAW_VERSION latest Pin OpenClaw version
HEALTH_PORT 7861 Health endpoint port

🤖 LLM Provider Setup

Just set LLM_MODEL with the correct provider prefix — the provider is auto-detected!

Anthropic (Claude) 

LLM_API_KEY=sk-ant-v0-...
LLM_MODEL=anthropic/claude-haiku-4-5

Models: anthropic/claude-opus-4-6 · anthropic/claude-sonnet-4-5 · anthropic/claude-haiku-4-5

OpenAI 

LLM_API_KEY=sk-...
LLM_MODEL=openai/gpt-4

Models: openai/gpt-4-turbo · openai/gpt-4 · openai/gpt-3.5-turbo

Google (Gemini) 

LLM_API_KEY=AIzaSy...
LLM_MODEL=google/gemini-2.5-flash

Models: google/gemini-2.5-flash · google/gemini-2.0-flash · google/gemini-1.5-pro

📱 Telegram Setup

  1. Message @BotFather → /newbot → copy the token
  2. Message @userinfobot to get your user ID
  3. Add secrets: TELEGRAM_BOT_TOKEN and TELEGRAM_USER_ID
  4. Restart the Space → DM your bot 🎉

Multiple users? Use TELEGRAM_USER_IDS=123,456,789 (comma-separated)

💾 Workspace Backup

Set HF_USERNAME + HF_TOKEN and HuggingClaw handles everything:

  1. Auto-creates the dataset if it doesn't exist
  2. Restores workspace on every startup
  3. Auto-syncs changes every 10 minutes (configurable)
  4. Saves on shutdown (graceful SIGTERM handling)

Custom dataset name: BACKUP_DATASET_NAME=my-custom-backup

💓 How It Stays Alive

HF Spaces sleeps after 48h of no HTTP requests. HuggingClaw prevents this with:

  • Self-ping — pings its own URL every 5 min (uses HF's SPACE_HOST env var)
  • Health endpoint — returns 200 OK with uptime info
  • Zero dependencies — no external cron, no third-party pinger

Your Space runs forever, powered entirely by HF. 🎯

💻 Local Development 

git clone https://github.com/somratpro/huggingclaw.git
cd huggingclaw
cp .env.example .env
nano .env  # fill in your values

Docker:

docker build -t huggingclaw .
docker run -p 7860:7860 --env-file .env huggingclaw

Without Docker:

npm install -g openclaw@latest
export $(cat .env | xargs)
bash start.sh

🔗 Connect via CLI 

npm install -g openclaw@latest
openclaw channels login --gateway https://YOUR-SPACE-URL.hf.space
# Enter your GATEWAY_TOKEN when prompted

🏗️ Architecture 

HuggingClaw/
├── Dockerfile          # Runtime: Node.js + OpenClaw + curl + jq
├── start.sh            # Config generator + validation + orchestrator
├── keep-alive.sh       # Self-ping to prevent HF sleep
├── workspace-sync.sh   # Periodic workspace commit + push
├── health-server.js    # Health endpoint (/health)
├── dns-fix.js          # DNS override for HF network restrictions
├── .env.example        # Complete configuration reference
├── .gitignore          # Keeps secrets out of version control
└── README.md           # You are here

Startup flow:

  1. Validate secrets → fail fast with clear errors
  2. Validate HF token → warn if expired
  3. Auto-create backup dataset if missing
  4. Restore workspace from HF Dataset
  5. Generate openclaw.json config from env vars
  6. Print startup summary
  7. Start background services (keep-alive, auto-sync)
  8. Launch OpenClaw gateway
  9. On SIGTERM → save workspace → exit cleanly

🐛 Troubleshooting

Missing secrets → Check Settings → Secrets for LLM_API_KEY and GATEWAY_TOKEN

Telegram not working → Verify bot token is valid, check logs for 📱 Enabling Telegram

Workspace not restoring → Check HF_USERNAME and HF_TOKEN are set, token has write access

Space sleeping → Check logs for 💓 Keep-alive started. If missing, SPACE_HOST might not be set

Control UI blocked → The Space URL is auto-allowlisted. Check logs for origin errors

Version issues → Pin with OPENCLAW_VERSION=2026.3.24 in secrets

📚 Links

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT — see LICENSE for details.

Made with ❤️ by @somratpro for the OpenClaw community