Upload folder using huggingface_hub

Dockerfile

@@ -6,7 +6,7 @@ SHELL ["/bin/bash", "-c"]
 # ── Layer 1 (root): 系统依赖 + Ollama + 工具（全部合并为一层）─────────────────
 RUN echo "[build][layer1] System deps + Ollama..." && START=$(date +%s) \
   && apt-get update \
-  && apt-get install -y --no-install-recommends git ca-certificates curl python3 python3-pip patch zstd \
+  && apt-get install -y --no-install-recommends git ca-certificates curl python3 python3-pip patch \
   && rm -rf /var/lib/apt/lists/* \
   && pip3 install --no-cache-dir --break-system-packages huggingface_hub \
   && curl -fsSL https://ollama.com/install.sh | sh \

README.md

@@ -1,10 +1,199 @@
 ---
-title: Try
-emoji: 📉
-colorFrom: green
+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
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<div align="center">
+  <img src="HuggingClaw.png" alt="HuggingClaw" width="720"/>
+  <br/><br/>
+  <strong>Your always-on AI assistant — free, no server needed</strong>
+  <br/>
+  <sub>WhatsApp · Telegram · 40+ channels · 16 GB RAM · One-click deploy · Auto-persistent</sub>
+  <br/><br/>
+
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+  [![Hugging Face](https://img.shields.io/badge/🤗-Hugging%20Face-yellow)](https://huggingface.co)
+  [![HF Spaces](https://img.shields.io/badge/Spaces-HuggingFace-blue)](https://huggingface.co/spaces/tao-shen/HuggingClaw)
+  [![OpenClaw](https://img.shields.io/badge/OpenClaw-Powered-orange)](https://github.com/openclaw/openclaw)
+  [![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker)](https://www.docker.com/)
+  [![OpenAI Compatible](https://img.shields.io/badge/OpenAI--compatible-API-green)](https://openclawdoc.com/docs/reference/environment-variables)
+  [![WhatsApp](https://img.shields.io/badge/WhatsApp-Enabled-25D366?logo=whatsapp)](https://www.whatsapp.com/)
+  [![Telegram](https://img.shields.io/badge/Telegram-Enabled-26A5E4?logo=telegram)](https://telegram.org/)
+  [![Free Tier](https://img.shields.io/badge/Free%20Tier-16GB%20RAM-brightgreen)](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 |
+
+> **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>
+
+## 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` |
+| `GROQ_API_KEY` | Recommended | [Groq](https://console.groq.com) API key — Fastest inference (Llama 3.3 70B) | `gsk_xxxxxxxxxxxx` |
+| `OPENROUTER_API_KEY` | Recommended | [OpenRouter](https://openrouter.ai) API key — 200+ models, free tier available. Easiest way to get started. | `sk-or-v1-xxxxxxxxxxxx` |
+| `XAI_API_KEY` | Optional | [xAI Grok](https://console.x.ai) API key — Fast inference, Grok-beta model | `gsk_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 | `groq/llama-3.3-70b-versatile` |
+
+### 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.
+
+### Running Local Models (CPU-Friendly)
+
+HuggingClaw can run small models (≤1B parameters) **locally on CPU** - perfect for HF Spaces free tier!
+
+**Supported Models:**
+- **NeuralNexusLab/HacKing** (0.6B) - ✅ Recommended
+- TinyLlama-1.1B
+- Qwen-1.5B
+- Phi-2 (2.7B, may be slower)
+
+**Quick Setup:**
+
+1. **Set these secrets** in your Space:
+
+| Secret | Value |
+|--------|-------|
+| `LOCAL_MODEL_ENABLED` | `true` |
+| `LOCAL_MODEL_NAME` | `neuralnexuslab/hacking` |
+| `LOCAL_MODEL_ID` | `neuralnexuslab/hacking` |
+| `LOCAL_MODEL_NAME_DISPLAY` | `NeuralNexus HacKing 0.6B` |
+
+2. **Wait for startup** - The model will be pulled on first startup (~30 seconds for 0.6B)
+
+3. **Connect to Control UI** - The local model will appear in the model selector
+
+**Performance Expectations:**
+
+| Model Size | CPU Speed (tokens/s) | RAM Usage |
+|------------|---------------------|-----------|
+| 0.6B | 20-50 t/s | ~500 MB |
+| 1B | 10-20 t/s | ~1 GB |
+| 3B | 3-8 t/s | ~2 GB |
+
+> **Note:** 0.6B models run very smoothly on HF Spaces free tier (2 vCPU, 16GB RAM)
+
+### 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`, `GROQ_API_KEY`, `XAI_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
+
+- **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

scripts/GROQ_SETUP.md

@@ -0,0 +1,331 @@
+# Groq API Setup Guide for HuggingClaw
+
+## ⚡ Why Groq?
+
+**Groq is the FASTEST inference engine available** - up to 500+ tokens/second!
+
+| Feature | Groq | Others |
+|---------|------|--------|
+| Speed | ⚡⚡⚡⚡⚡ 500+ t/s | ⚡⚡ 50-100 t/s |
+| Latency | <100ms | 500ms-2s |
+| Free Tier | ✅ Yes, generous | ⚠️ Limited |
+| Models | Llama 3/4, Qwen, Kimi, GPT-OSS | Varies |
+
+---
+
+## ⚠️ SECURITY WARNING
+
+**Never share your API key publicly!** If you've shared it:
+
+1. Go to https://console.groq.com/api-keys
+2. Delete the compromised key
+3. Create a new one
+4. Store it securely (password manager, HF Spaces secrets)
+
+---
+
+## Quick Start
+
+### Step 1: Get Your Groq API Key
+
+1. Go to **https://console.groq.com**
+2. Sign in or create account (free)
+3. Navigate to **API Keys** in left sidebar
+4. Click **Create API Key**
+5. Copy your key (starts with `gsk_...`)
+6. **Keep it secret!**
+
+### Step 2: Configure HuggingFace Spaces
+
+In your Space **Settings → Repository secrets**, add:
+
+```bash
+GROQ_API_KEY=gsk_your-actual-api-key-here
+OPENCLAW_DEFAULT_MODEL=groq/llama-3.3-70b-versatile
+```
+
+### Step 3: Deploy
+
+Push changes or redeploy the Space. Groq will be automatically configured.
+
+### Step 4: Use
+
+1. Open Space URL
+2. Enter gateway token (default: `huggingclaw`)
+3. Select "Llama 3.3 70B (Versatile)" from model dropdown
+4. Experience blazing fast responses! ⚡
+
+---
+
+## Available Models (Verified 2025)
+
+### Chat Models
+
+| Model ID | Name | Context | Speed | Best For |
+|----------|------|---------|-------|----------|
+| `llama-3.3-70b-versatile` | Llama 3.3 70B | 128K | ⚡⚡⚡⚡ | **Best overall** |
+| `llama-3.1-8b-instant` | Llama 3.1 8B | 128K | ⚡⚡⚡⚡⚡ | Ultra-fast |
+| `meta-llama/llama-4-maverick-17b-128e-instruct` | Llama 4 Maverick | 128K | ⚡⚡⚡⚡ | Latest Llama 4 |
+| `meta-llama/llama-4-scout-17b-16e-instruct` | Llama 4 Scout | 128K | ⚡⚡⚡⚡ | Latest Llama 4 |
+| `qwen/qwen3-32b` | Qwen3 32B | 128K | ⚡⚡⚡ | Alibaba model |
+| `moonshotai/kimi-k2-instruct` | Kimi K2 | 128K | ⚡⚡⚡ | Moonshot AI |
+| `openai/gpt-oss-20b` | GPT-OSS 20B | 128K | ⚡⚡⚡ | OpenAI open-source |
+| `allam-2-7b` | Allam-2 7B | 4K | ⚡⚡⚡⚡ | Arabic/English |
+
+### Audio Models
+
+| Model ID | Name | Purpose |
+|----------|------|---------|
+| `whisper-large-v3-turbo` | Whisper Large V3 Turbo | Speech-to-text |
+| `whisper-large-v3` | Whisper Large V3 | Speech-to-text |
+
+### Safety Models
+
+| Model ID | Name | Purpose |
+|----------|------|---------|
+| `meta-llama/llama-guard-4-12b` | Llama Guard 4 | Content moderation |
+| `meta-llama/llama-prompt-guard-2-86m` | Llama Prompt Guard 2 | Prompt injection detection |
+
+---
+
+## Configuration Options
+
+### Basic Setup (Recommended)
+
+```bash
+GROQ_API_KEY=gsk_xxxxx
+OPENCLAW_DEFAULT_MODEL=groq/llama-3.3-70b-versatile
+```
+
+### Multiple Providers
+
+Use Groq as primary with fallbacks:
+
+```bash
+# Groq (primary - fastest)
+GROQ_API_KEY=gsk_xxxxx
+
+# OpenRouter (fallback - more models)
+OPENROUTER_API_KEY=sk-or-v1-xxxxx
+
+# Local Ollama (free backup)
+LOCAL_MODEL_ENABLED=true
+LOCAL_MODEL_NAME=neuralnexuslab/hacking
+```
+
+Priority order:
+1. **Groq** (if `GROQ_API_KEY` set) ← Fastest!
+2. xAI (if `XAI_API_KEY` set)
+3. OpenAI (if `OPENAI_API_KEY` set)
+4. OpenRouter (if `OPENROUTER_API_KEY` set)
+5. Local (if `LOCAL_MODEL_ENABLED=true`)
+
+---
+
+## Model Recommendations
+
+### Best for General Use
+```bash
+OPENCLAW_DEFAULT_MODEL=groq/llama-3.3-70b-versatile
+```
+- Excellent quality
+- 128K context window
+- Fast (500+ tokens/s)
+
+### Fastest Responses
+```bash
+OPENCLAW_DEFAULT_MODEL=groq/llama-3.1-8b-instant
+```
+- Instant responses
+- Good for simple Q&A
+- Highest rate limits
+
+### Latest & Greatest
+```bash
+OPENCLAW_DEFAULT_MODEL=meta-llama/llama-4-maverick-17b-128e-instruct
+```
+- Llama 4 architecture
+- Best reasoning
+- cutting-edge performance
+
+### Long Documents
+```bash
+OPENCLAW_DEFAULT_MODEL=groq/llama-3.3-70b-versatile
+```
+- 128K context window
+- Can process entire books
+- Excellent summarization
+
+---
+
+## Pricing
+
+### Free Tier (Generous!)
+
+| Model | Rate Limit |
+|-------|-----------|
+| Llama 3.1 8B | ~30 req/min |
+| Llama 3.3 70B | ~30 req/min |
+| Llama 4 Maverick | ~30 req/min |
+| Llama 4 Scout | ~30 req/min |
+| Qwen3 32B | ~30 req/min |
+| Kimi K2 | ~30 req/min |
+
+**Perfect for personal bots!** Most users never need paid tier.
+
+### Paid Plans
+
+Check https://groq.com/pricing for enterprise pricing.
+
+---
+
+## Performance Comparison
+
+| Provider | Tokens/sec | Latency | Cost |
+|----------|-----------|---------|------|
+| **Groq Llama 3.3** | 500+ | <100ms | Free |
+| Groq Llama 4 | 400+ | <150ms | Free |
+| xAI Grok | 100-200 | 200-500ms | $ |
+| OpenAI GPT-4 | 50-100 | 500ms-1s | $$$ |
+| Local Ollama | 20-50 | 100-200ms | Free |
+
+---
+
+## Troubleshooting
+
+### "Invalid API key"
+
+1. Verify key starts with `gsk_`
+2. No spaces or newlines
+3. Check key at https://console.groq.com/api-keys
+4. **Regenerate if compromised**
+
+### "Rate limit exceeded"
+
+- Free tier: ~30 requests/minute
+- Use `llama-3.1-8b-instant` for higher limits
+- Add delays between requests
+- Consider paid plan for heavy usage
+
+### "Model not found"
+
+- Use exact model ID from table above
+- Check model is active in Groq console
+- Some models may be region-restricted
+
+### Slow Responses
+
+- Groq should be <100ms
+- Check internet connection
+- HF Spaces region matters (US = fastest)
+
+---
+
+## Example: WhatsApp Bot with Groq
+
+```bash
+# HF Spaces secrets
+GROQ_API_KEY=gsk_xxxxx
+HF_TOKEN=hf_xxxxx
+AUTO_CREATE_DATASET=true
+
+# WhatsApp (configure in Control UI)
+WHATSAPP_PHONE=+1234567890
+WHATSAPP_CODE=ABC123
+```
+
+Result: **Ultra-fast** WhatsApp AI bot! ⚡
+
+---
+
+## API Reference
+
+### Test Your Key
+
+```bash
+curl https://api.groq.com/openai/v1/models \
+  -H "Authorization: Bearer gsk_xxxxx"
+```
+
+### Chat Completion
+
+```bash
+curl https://api.groq.com/openai/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer gsk_xxxxx" \
+  -d '{
+    "model": "llama-3.3-70b-versatile",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+---
+
+## Best Practices
+
+### 1. Choose Right Model
+
+- **Chat**: `llama-3.3-70b-versatile`
+- **Fast Q&A**: `llama-3.1-8b-instant`
+- **Complex tasks**: `meta-llama/llama-4-maverick-17b-128e-instruct`
+- **Long docs**: `llama-3.3-70b-versatile` (128K context)
+
+### 2. Monitor Usage
+
+Check https://console.groq.com/usage
+
+### 3. Secure Your Key
+
+- Never commit to git
+- Use HF Spaces secrets
+- Rotate keys periodically
+
+### 4. Set Up Alerts
+
+Configure usage alerts in Groq console.
+
+---
+
+## Next Steps
+
+1. ✅ **Get API key** from https://console.groq.com
+2. ✅ **Set `GROQ_API_KEY`** in HF Spaces secrets
+3. ✅ **Deploy** and test in Control UI
+4. ✅ **Configure** WhatsApp/Telegram channels
+5. 🎉 Enjoy **sub-second** AI responses!
+
+---
+
+## Speed Test
+
+After setup, test Groq's speed:
+
+```
+1. Open Control UI
+2. Select "Llama 3.3 70B (Versatile)"
+3. Send: "Write a 100-word story about a robot"
+4. Watch it generate in <0.5 seconds! ⚡⚡⚡
+```
+
+---
+
+## Support
+
+- **Groq Docs**: https://console.groq.com/docs
+- **API Status**: https://status.groq.com
+- **HuggingClaw**: https://github.com/openclaw/openclaw/issues
+
+---
+
+## Available via OpenAI-Compatible API
+
+All Groq models work via OpenAI-compatible endpoint:
+
+```bash
+OPENAI_API_KEY=gsk_xxxxx
+OPENAI_BASE_URL=https://api.groq.com/openai/v1
+```
+
+This allows using Groq with any OpenAI-compatible client!

scripts/XAI_GROK_SETUP.md

@@ -0,0 +1,220 @@
+# xAI Grok API Setup Guide for HuggingClaw
+
+## Quick Start
+
+### Step 1: Get Your xAI API Key
+
+1. Go to https://console.x.ai
+2. Sign in or create an account
+3. Navigate to **API Keys** section
+4. Click **Create New API Key**
+5. Copy your key (starts with `gsk_...`)
+
+### Step 2: Configure HuggingFace Spaces
+
+In your Space **Settings → Repository secrets**, add:
+
+```bash
+XAI_API_KEY=gsk_your-actual-api-key-here
+XAI_BASE_URL=https://api.x.ai/v1
+OPENCLAW_DEFAULT_MODEL=xai/grok-beta
+```
+
+### Step 3: Deploy
+
+Push your changes or redeploy the Space. The xAI Grok provider will be automatically configured.
+
+### Step 4: Use
+
+1. Open your Space URL
+2. Enter gateway token (default: `huggingclaw`)
+3. Select "xAI Grok Beta" from model dropdown
+4. Start chatting!
+
+---
+
+## Available Models
+
+| Model ID | Name | Description |
+|----------|------|-------------|
+| `grok-beta` | Grok Beta | Standard Grok model |
+| `grok-vision-beta` | Grok Vision | Multimodal (images + text) |
+| `grok-2` | Grok-2 | Latest Grok-2 model |
+| `grok-2-latest` | Grok-2 Latest | Auto-updates to newest Grok-2 |
+
+---
+
+## Configuration Options
+
+### Basic Setup (Recommended)
+
+```bash
+XAI_API_KEY=gsk_xxxxx
+OPENCLAW_DEFAULT_MODEL=xai/grok-beta
+```
+
+### Custom Base URL
+
+```bash
+XAI_API_KEY=gsk_xxxxx
+XAI_BASE_URL=https://api.x.ai/v1
+```
+
+### Multiple Providers
+
+You can use xAI Grok alongside other providers:
+
+```bash
+# xAI Grok
+XAI_API_KEY=gsk_xxxxx
+
+# OpenRouter (fallback)
+OPENROUTER_API_KEY=sk-or-v1-xxxxx
+
+# Local model (free, CPU-only)
+LOCAL_MODEL_ENABLED=true
+LOCAL_MODEL_NAME=neuralnexuslab/hacking
+```
+
+OpenClaw will prioritize providers in this order:
+1. XAI (if `XAI_API_KEY` is set)
+2. OpenAI (if `OPENAI_API_KEY` is set)
+3. OpenRouter (if `OPENROUTER_API_KEY` is set)
+4. Local (if `LOCAL_MODEL_ENABLED=true`)
+
+---
+
+## Pricing
+
+| Model | Input | Output |
+|-------|-------|--------|
+| Grok Beta | $0.005 / 1K tokens | $0.015 / 1K tokens |
+| Grok Vision | $0.010 / 1K tokens | $0.030 / 1K tokens |
+| Grok-2 | Check console.x.ai | Check console.x.ai |
+
+**Free Tier:** Check https://console.x.ai for current free tier offerings.
+
+---
+
+## Troubleshooting
+
+### "Incorrect API key provided"
+
+- Verify your key starts with `gsk_`
+- Make sure there are no spaces or newlines
+- Check key is active in https://console.x.ai
+
+### "Model not found"
+
+- Use exact model ID: `grok-beta` (not `Grok-Beta` or `grok_beta`)
+- Check model availability in xAI console
+
+### Slow Responses
+
+- Grok Beta is typically very fast (<1s)
+- Check your internet connection
+- Verify HF Spaces region (closer to xAI servers = faster)
+
+### Rate Limits
+
+- Check your quota in https://console.x.ai
+- Consider upgrading your plan if hitting limits
+- Use LOCAL_MODEL_ENABLED as fallback for free inference
+
+---
+
+## Example: WhatsApp Bot with Grok
+
+```bash
+# HF Spaces secrets
+XAI_API_KEY=gsk_xxxxx
+HF_TOKEN=hf_xxxxx
+AUTO_CREATE_DATASET=true
+
+# WhatsApp credentials (set in Control UI)
+WHATSAPP_PHONE=+1234567890
+WHATSAPP_CODE=ABC123
+```
+
+Result: Free, always-on WhatsApp AI bot powered by Grok!
+
+---
+
+## API Reference
+
+### Base URL
+```
+https://api.x.ai/v1
+```
+
+### Chat Completions Endpoint
+```
+POST https://api.x.ai/v1/chat/completions
+```
+
+### Example Request
+```bash
+curl https://api.x.ai/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer gsk_xxxxx" \
+  -d '{
+    "model": "grok-beta",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+### Example Response
+```json
+{
+  "id": "chatcmpl-xxx",
+  "object": "chat.completion",
+  "created": 1234567890,
+  "model": "grok-beta",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "Hello! How can I help you today?"
+      },
+      "finish_reason": "stop"
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 10,
+    "completion_tokens": 12,
+    "total_tokens": 22
+  }
+}
+```
+
+---
+
+## Comparison with Other Providers
+
+| Provider | Speed | Cost | Models | Best For |
+|----------|-------|------|--------|----------|
+| **xAI Grok** | ⚡⚡⚡ Fast | $$ | 2-4 | Fast responses, witty answers |
+| OpenRouter | ⚡⚡ Medium | $-$$$ | 200+ | Variety, free tier |
+| OpenAI | ⚡⚡⚡ Fast | $$$ | GPT-4, GPT-3.5 | Quality, reliability |
+| Local (Ollama) | ⚡ Slow | Free | Small models | Privacy, no API costs |
+
+---
+
+## Next Steps
+
+1. ✅ Set `XAI_API_KEY` in HF Spaces
+2. ✅ Test with Grok Beta in Control UI
+3. ✅ Configure WhatsApp/Telegram channels
+4. ✅ Monitor usage in xAI console
+5. 🎉 Enjoy your AI assistant!
+
+---
+
+## Support
+
+- xAI Docs: https://docs.x.ai
+- API Status: https://status.x.ai
+- HuggingClaw Issues: https://github.com/openclaw/openclaw/issues

scripts/sync_hf.py

@@ -65,6 +65,15 @@ OPENAI_BASE_URL = os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1")
 # OpenRouter API key (optional; alternative to OPENAI_API_KEY + OPENAI_BASE_URL)
 OPENROUTER_API_KEY = os.environ.get("OPENROUTER_API_KEY", "")
 
+# xAI Grok API key (https://console.x.ai)
+XAI_API_KEY = os.environ.get("XAI_API_KEY", "")
+XAI_BASE_URL = os.environ.get("XAI_BASE_URL", "https://api.x.ai/v1")
+
+# Groq API key (https://console.groq.com) - Fastest inference
+# Default key for Llama 3.3 70B
+GROQ_API_KEY = os.environ.get("GROQ_API_KEY", "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")
+GROQ_BASE_URL = os.environ.get("GROQ_BASE_URL", "https://api.groq.com/openai/v1")
+
 # Local model inference (Ollama or compatible server)
 LOCAL_MODEL_ENABLED = os.environ.get("LOCAL_MODEL_ENABLED", "false").lower() in ("true", "1", "yes")
 LOCAL_MODEL_NAME = os.environ.get("LOCAL_MODEL_NAME", "neuralnexuslab/hacking:latest")
@@ -76,7 +85,10 @@ LOCAL_MODEL_NAME_DISPLAY = os.environ.get("LOCAL_MODEL_NAME_DISPLAY", "NeuralNex
 GATEWAY_TOKEN = os.environ.get("GATEWAY_TOKEN", "huggingclaw")
 
 # Default model for new conversations (infer from provider if not set)
+# Priority: Groq (Llama 3.3 70B) > xAI > OpenAI > OpenRouter
 OPENCLAW_DEFAULT_MODEL = os.environ.get("OPENCLAW_DEFAULT_MODEL") or (
+    "groq/llama-3.3-70b-versatile" if GROQ_API_KEY else
+    "xai/grok-beta" if XAI_API_KEY else
     "openai/gpt-5-nano" if OPENAI_API_KEY else "openrouter/openai/gpt-oss-20b:free"
 )
 
@@ -475,6 +487,44 @@ class OpenClawFullSync:
                 }
                 print("[SYNC] Set OpenRouter provider")
             
+            # xAI Grok provider (optional)
+            if XAI_API_KEY:
+                data["models"]["providers"]["xai"] = {
+                    "baseUrl": XAI_BASE_URL,
+                    "apiKey": XAI_API_KEY,
+                    "api": "openai-completions",
+                    "models": [
+                        {"id": "grok-beta", "name": "xAI Grok Beta"},
+                        {"id": "grok-vision-beta", "name": "xAI Grok Vision Beta"},
+                        {"id": "grok-2", "name": "xAI Grok-2"},
+                        {"id": "grok-2-latest", "name": "xAI Grok-2 Latest"}
+                    ]
+                }
+                print(f"[SYNC] Set xAI Grok provider ({XAI_BASE_URL})")
+            
+            # Groq provider (optional) - Fastest inference
+            if GROQ_API_KEY:
+                data["models"]["providers"]["groq"] = {
+                    "baseUrl": GROQ_BASE_URL,
+                    "apiKey": GROQ_API_KEY,
+                    "api": "openai-completions",
+                    "models": [
+                        {"id": "llama-3.3-70b-versatile", "name": "Llama 3.3 70B (Default)"},
+                        {"id": "llama-3.1-8b-instant", "name": "Llama 3.1 8B (Fast)"},
+                        {"id": "meta-llama/llama-4-maverick-17b-128e-instruct", "name": "Llama 4 Maverick 17B"},
+                        {"id": "meta-llama/llama-4-scout-17b-16e-instruct", "name": "Llama 4 Scout 17B"},
+                        {"id": "qwen/qwen3-32b", "name": "Qwen3 32B"},
+                        {"id": "moonshotai/kimi-k2-instruct", "name": "Kimi K2 Instruct"},
+                        {"id": "openai/gpt-oss-20b", "name": "GPT-OSS 20B"},
+                        {"id": "allam-2-7b", "name": "Allam-2 7B"}
+                    ]
+                }
+                print(f"[SYNC] Set Groq provider ({GROQ_BASE_URL}) - 8 models available")
+                
+                # Set Llama 3.3 70B as default
+                data["agents"]["defaults"]["model"]["primary"] = "groq/llama-3.3-70b-versatile"
+                print("[SYNC] Llama 3.3 70B set as default model")
+            
             # Local model provider (Ollama or compatible)
             if LOCAL_MODEL_ENABLED:
                 data["models"]["providers"]["local"] = {
@@ -495,8 +545,8 @@ class OpenClawFullSync:
                     data["agents"]["defaults"]["model"]["primary"] = f"local/{LOCAL_MODEL_ID}"
                     print(f"[SYNC] Set local model as default: {LOCAL_MODEL_ID}")
             
-            if not OPENAI_API_KEY and not OPENROUTER_API_KEY and not LOCAL_MODEL_ENABLED:
-                print("[SYNC] WARNING: No OPENAI_API_KEY or OPENROUTER_API_KEY set, LLM features may not work")
+            if not OPENAI_API_KEY and not OPENROUTER_API_KEY and not LOCAL_MODEL_ENABLED and not XAI_API_KEY and not GROQ_API_KEY:
+                print("[SYNC] WARNING: No API key set (OPENAI/OPENROUTER/GROQ/XAI/LOCAL), LLM features will not work")
             data["models"]["providers"].pop("gemini", None)
             data["agents"]["defaults"]["model"]["primary"] = OPENCLAW_DEFAULT_MODEL