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:

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)

XAI_API_KEY=gsk_xxxxx
OPENCLAW_DEFAULT_MODEL=xai/grok-beta

Custom Base URL

XAI_API_KEY=gsk_xxxxx
XAI_BASE_URL=https://api.x.ai/v1

Multiple Providers

You can use xAI Grok alongside other providers:

# 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

# 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

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

{
  "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