scripts/XAI_GROK_SETUP.md

# 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