https://api.x.ai/v1 — this is the single config field that blocks most failed connections. It must be set in your provider block.console.x.ai — not X.com account settings. Keys start with xai-.GROK_API_KEY and XAI_API_KEY — either works with the grok provider block.grok-2 and grok-2-mini — the hyphen is required. "grok2" without a hyphen returns a 404.openclaw doctor --provider grok immediately after setup — a failed doctor check is always fixable and always better to catch before deployment.Grok is xAI's flagship model — and as of early 2025, its API access is one of the fastest provider setups you can do with OpenClaw. The entire configuration takes three fields in your openclaw.yaml. The reason 80% of builders fail isn't the key setup — it's missing the base URL field. Here is the complete setup so you don't waste time debugging a one-line fix.
Getting Your Key from console.x.ai
Go to console.x.ai. Sign in with your X (formerly Twitter) account. Navigate to "API Keys" in the left panel. Click "Create API Key," give it a name, and copy the key immediately — xAI shows the full key only once on creation.
Grok API keys start with xai-. If your key doesn't have this prefix, you're looking at the wrong credential type. The key format is long — it starts with xai- and is followed by a long alphanumeric string.
Setting the Environment Variable
OpenClaw's grok provider block accepts two variable names — use whichever fits your setup:
# Option 1 — preferred convention
export GROK_API_KEY="xai-your-key-here"
# Option 2 — also accepted by OpenClaw's grok provider
export XAI_API_KEY="xai-your-key-here"
# Windows PowerShell
$env:GROK_API_KEY="xai-your-key-here"
# .env file
GROK_API_KEY=xai-your-key-hereThe Complete openclaw.yaml Config
This is the complete provider block. Every field is required — particularly the base_url, which is the field that breaks connections when omitted.
providers:
grok:
api_key: "${GROK_API_KEY}"
base_url: "https://api.x.ai/v1"
default_model: grok-2
models:
- id: grok-2
context_window: 131072
cost_tier: standard
- id: grok-2-mini
context_window: 131072
cost_tier: economy
agents:
reasoning-agent:
provider: grok
model: grok-2
description: "Complex reasoning and analysis tasks"
fast-response:
provider: grok
model: grok-2-mini
description: "Quick classification and routing tasks"Grok Model Strings
Two models are available through the xAI API as of early 2025:
grok-2— Full-capability model. Strong reasoning, 131k context. Use for complex tasks where quality matters more than speed.grok-2-mini— Faster and cheaper. Same context window. Use for classification, routing, and quick-turnaround tasks.
The hyphen in both model names is required. "grok2" without the hyphen returns a model-not-found error from xAI's API. "grok-1" references the previous generation and is deprecated. Stick to the exact strings above.
The One Mistake That Blocks Connections
Here's the failure pattern we see consistently: a builder sets their API key correctly, writes a valid provider block, and then gets a connection error on every request. The diagnosis is always the same — the base_url field is missing.
Without base_url set, OpenClaw defaults to the OpenAI endpoint (https://api.openai.com/v1). Your xAI key doesn't work there. Every request fails with an authentication error that looks like a key problem but isn't.
https://api.x.ai/v1 — no trailing slash, version suffix included. If you omit this field or set it incorrectly, OpenClaw sends your API key to the wrong endpoint and every request returns a 401. This is not a key validity problem — it's a routing problem.Rate Limits on Early Access
xAI's early access tier enforces conservative rate limits while their infrastructure scales. As of early 2025, typical limits are 60 requests per minute with daily token caps that scale with your account tier. Check your current limits in the console.x.ai dashboard under Usage.
Implement retry logic for any production Grok integration — rate limit behavior can change as xAI updates their access tiers:
providers:
grok:
api_key: "${GROK_API_KEY}"
base_url: "https://api.x.ai/v1"
default_model: grok-2
retry:
max_attempts: 3
initial_delay_ms: 1000
backoff_multiplier: 2
retry_on: [429, 503]The 1000ms initial delay is conservative — Grok's rate limit windows reset quickly, and a brief pause on the first retry usually resolves transient 429 errors without needing to wait for the full backoff sequence.
Testing the Connection
# Full provider health check
openclaw doctor --provider grok
# Test a specific model
openclaw test-model grok-2 --provider grok --prompt "Respond with OK"
# Test the mini model
openclaw test-model grok-2-mini --provider grok --prompt "Respond with OK"A passing openclaw doctor check confirms three things: the API key is valid, the base URL resolves, and the model strings are recognized by xAI's API. If any of these fail, the doctor output tells you which one.
If you get "connection refused" rather than an authentication error, the base_url is the problem. If you get a 401, the API key is wrong or the environment variable isn't set. If you get a 404, the model string is incorrect.
Frequently Asked Questions
Where do I get a Grok API key for OpenClaw?
Get your Grok API key from console.x.ai — xAI's developer console. Sign in with your X account, navigate to API Keys, and generate a new key. The key format starts with 'xai-'. Set it as GROK_API_KEY in your environment before configuring OpenClaw's provider block.
What environment variable does OpenClaw use for Grok?
OpenClaw accepts either GROK_API_KEY or XAI_API_KEY — both work with the grok provider block. GROK_API_KEY is the preferred convention. If you've already set XAI_API_KEY in your environment from another tool, reference that variable directly in your openclaw.yaml api_key field.
What is the correct base URL for Grok in OpenClaw?
The xAI API base URL is https://api.x.ai/v1 — this must be set in your OpenClaw provider block. Without it, OpenClaw sends requests to the wrong endpoint and receives connection errors. This is the single most common Grok setup mistake and the one that blocks nearly every failed connection.
Which Grok model strings work with OpenClaw?
Use grok-2 for full-capability tasks and grok-2-mini for faster, cheaper responses on simpler tasks. Both are available through the xAI API as of early 2025. The hyphen is required in both strings — 'grok2' without a hyphen and 'grok-1' both return 404 errors from xAI's API.
What are Grok's rate limits on early access?
Grok's early access tier enforces conservative rate limits while xAI scales infrastructure — typically 60 requests per minute with daily token caps that vary by account tier. Check your current limits in the console.x.ai dashboard and implement retry logic with exponential backoff for production workloads.
How do I verify my Grok connection in OpenClaw?
Run openclaw doctor --provider grok after configuration. A passing check confirms the API key is valid, the base URL resolves, and your model strings are recognized. If the doctor check fails with 'connection refused', the base_url is either missing from your config or set to the wrong endpoint.
A. Larsen has integrated xAI's Grok API into three production OpenClaw deployments since early access opened, debugging the configuration failures that tripped up early adopters. She documented the base URL failure pattern after seeing it repeat across multiple teams independently. Based in Copenhagen, she focuses on API integration patterns, authentication flows, and provider-specific configuration edge cases.
You now have every piece of the Grok setup: key creation, environment variable, YAML config with the base URL that matters, model strings, and retry logic for rate limits.
Run openclaw doctor --provider grok and you'll see green across the board.
No extra setup required beyond your xAI account. Takes under 3 minutes.
→ Next: Understand Codex OAuth — the auth setup most guides get wrong