🦞 Grok for OpenClaw

Add xAI Grok (Grok 3, Grok 4, Grok 4.1) support to OpenClaw with one command.

v1.0 stable · by ROOH

⚡ TL;DR — Quick Start

git clone https://github.com/roohcode/grok-for-openclaw.git
cd grok-for-openclaw
./install.sh

The installer will:

1. Ask for your xAI API key (get one here)
2. Validate the key against the xAI API
3. Auto-detect which Grok models you have access to
4. Let you choose your default model
5. Patch your OpenClaw config and restart the gateway

Manual install? Jump to Manual Installation.

---

The Problem

OpenClaw does not natively support xAI's Grok models. If you try adding Grok through the config wizard or using common API type values like "openai-compatible" or "openai", you'll get:

Config invalid: models.providers.xai.api: Invalid input

The Fix

xAI's API uses the same format as OpenAI's Chat Completions API (/v1/chat/completions). OpenClaw supports this through its openai-completions API type — a value discovered by analyzing OpenClaw's source code (Zod schema validation).

What doesn't work	What works
"api": "openai-compatible" ❌	"api": "openai-completions" ✅
"api": "openai" ❌
"api": "xai" ❌
"api": "grok" ❌

Installation

One-Click Install

git clone https://github.com/roohcode/grok-for-openclaw.git
cd grok-for-openclaw
./install.sh

Pass your API key directly:

./install.sh xai-YOUR_API_KEY_HERE

Or via environment variable:

XAI_API_KEY=xai-YOUR_KEY ./install.sh

Uninstall

./uninstall.sh

Available Models

Model	OpenClaw ID	Type	Context
Grok 4.1 Thinking	xai/grok-4-1-fast-reasoning	Reasoning	131K
Grok 4.1 Fast	xai/grok-4-1-fast-non-reasoning	Fast	131K
Grok 4	xai/grok-4-0709	Reasoning	131K
Grok 4 Thinking	xai/grok-4-fast-reasoning	Reasoning	131K
Grok 4 Fast	xai/grok-4-fast-non-reasoning	Fast	131K
Grok 3	xai/grok-3	Reasoning	131K
Grok 3 Mini	xai/grok-3-mini	Lightweight	131K
Grok 2 Vision	xai/grok-2-vision-1212	Vision	32K

Prerequisites

• OpenClaw installed and running (~/.openclaw/openclaw.json exists)
• xAI API key from console.x.ai (with credits added)
• Python 3 (pre-installed on macOS; apt install python3 on Linux)

Manual Installation

Step 1: Get Your xAI API Key

1. Go to console.x.ai
2. Create an account or sign in
3. Navigate to API Keys and create a new key (starts with xai-)
4. Add credits to your account

Step 2: Edit OpenClaw Config

Open ~/.openclaw/openclaw.json and add the "xai" block inside "models" → "providers":

"xai": {
  "baseUrl": "https://api.x.ai/v1",
  "apiKey": "YOUR_XAI_API_KEY_HERE",
  "api": "openai-completions",
  "models": [
    {
      "id": "grok-4-1-fast-reasoning",
      "name": "Grok 4.1 Thinking",
      "reasoning": true,
      "input": ["text", "image"],
      "contextWindow": 131072,
      "maxTokens": 131072
    }
  ]
}

⚠️ Critical: The "api" value MUST be exactly "openai-completions".

See config/grok-provider.json for the full template with all 8 models.

Step 3: Set Default Model (Optional)

"primary": "xai/grok-4-1-fast-reasoning"

Step 4: Restart OpenClaw

# macOS
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

# Linux
systemctl --user restart openclaw-gateway

Step 5: Verify

tail -n 5 ~/.openclaw/logs/gateway.err.log

No "Invalid input" errors = success.

Configuration

Changing the Default Model

Edit ~/.openclaw/openclaw.json:

"primary": "xai/grok-3"

Then restart the gateway.

API Connection Settings

Setting	Value	Notes
baseUrl	https://api.x.ai/v1	Fixed — xAI's only endpoint
apiKey	xai-...	Get from console.x.ai
api	openai-completions	Do not change

Test API Key Manually

curl https://api.x.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xai-YOUR_KEY" \
  -d '{"model":"grok-4-1-fast-reasoning","messages":[{"role":"user","content":"Hello"}]}'

How It Works

OpenClaw validates its config using Zod schemas. The valid API types were found by extracting Zod literals from OpenClaw's bundled JavaScript:

API Type	Provider
google-generative-ai	Google AI Studio
google-vertex	Google Vertex AI
anthropic-messages	Anthropic Claude
openai-completions	OpenAI Chat Completions (xAI uses this)
openai-responses	OpenAI Responses API
bedrock-converse-stream	AWS Bedrock
perplexity	Perplexity AI

xAI implements the OpenAI Chat Completions spec. By setting "api": "openai-completions" and "baseUrl": "https://api.x.ai/v1", OpenClaw sends requests to xAI. No custom code needed.

Security

• API keys are never logged or exposed in process listings
• Key input uses hidden prompt (read -sp) in interactive mode
• Config backups are created with restricted permissions (600)
• Original file permissions are preserved after patching
• All Python operations use environment variables, not shell interpolation

Troubleshooting

Issue	Fix
Config invalid: models.providers.xai.api	"api" must be exactly "openai-completions"
429 RESOURCE_EXHAUSTED	Add credits at console.x.ai
401 Unauthorized	Check your API key is correct
Gateway won't start	Check JSON: python3 -c "import json; json.load(open('$HOME/.openclaw/openclaw.json'))"
Python not found	brew install python3 (macOS) or apt install python3 (Linux)

License

MIT — Free to use, modify, and distribute.

Credits

Created by ROOH · Discovered by analyzing OpenClaw v2026.2.9 source code.

This module is not affiliated with xAI or OpenClaw.