> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# xAI
OpenClaw ships a bundled `xai` provider plugin for Grok models. The
recommended path is Grok OAuth with an eligible SuperGrok or X Premium
subscription. Gateway, config, routing, and tools stay local; only Grok
requests go to xAI's API.
OAuth does not require an xAI API key or the Grok Build app. xAI may still
show Grok Build on the consent screen because OpenClaw uses xAI's shared
OAuth client.
## Setup
Run onboarding with daemon install, then pick xAI/Grok OAuth at the
model/auth step:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw onboard --install-daemon
```
On a VPS or over SSH, select xAI OAuth directly; it uses device-code
verification and does not need a localhost callback:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw onboard --install-daemon --auth-choice xai-oauth
```
Sign in to xAI only; do not rerun full onboarding just to connect Grok:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw models auth login --provider xai --method oauth
```
Apply Grok as the default model separately:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw models set xai/grok-4.3
```
Rerun full onboarding only if you intentionally want to change Gateway,
daemon, channel, workspace, or other setup choices.
API-key setup still works for xAI Console keys and for media surfaces
that need key-backed provider config:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw models auth login --provider xai --method api-key
export XAI_API_KEY=xai-...
```
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
agents: { defaults: { model: { primary: "xai/grok-4.3" } } },
}
```
OpenClaw uses the xAI Responses API as the bundled xAI transport. The same
credential from `openclaw models auth login --provider xai --method oauth` or
`--method api-key` also powers `web_search` (provider id `grok`), `x_search`,
`code_execution`, speech/transcription, and xAI image/video generation. If you
store an xAI key under `plugins.entries.xai.config.webSearch.apiKey`, the
bundled xAI model provider reuses it as a fallback too.
## OAuth troubleshooting
* For SSH, Docker, VPS, or other remote setups, use
`openclaw models auth login --provider xai --method oauth`; it uses
device-code verification, not a localhost callback.
* If sign-in succeeds but Grok is not the default model, run
`openclaw models set xai/grok-4.3`.
* Inspect saved xAI auth profiles:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw models auth list --provider xai
openclaw models status
```
* xAI decides which accounts can receive OAuth API tokens. If an account is
not eligible, use the API-key path or check the subscription on xAI's side.
Use `xai-oauth` when signing in from SSH, Docker, or a VPS. OpenClaw prints a
URL and short code; finish sign-in in any local browser while the remote
process polls xAI for the completed token exchange.
## Built-in catalog
Selectable ids in model pickers. The plugin still resolves older Grok 3,
Grok 4, Grok 4 Fast, Grok 4.1 Fast, and Grok Code ids for existing configs;
see [legacy compatibility aliases](#legacy-compatibility-aliases).
| Family | Model ids |
| -------------- | ------------------------------------------------------------------------ |
| Grok Build 0.1 | `grok-build-0.1` |
| Grok 4.3 | `grok-4.3` |
| Grok 4.20 Beta | `grok-4.20-beta-latest-reasoning`, `grok-4.20-beta-latest-non-reasoning` |
Use `grok-4.3` for general chat and `grok-build-0.1` for build/coding-focused
workloads unless you need a Grok 4.20 beta alias.
## Feature coverage
The bundled plugin maps xAI's current public API surface onto OpenClaw's
shared provider and tool contracts. Capabilities that do not fit the shared
contract, such as streaming TTS and realtime voice, are not exposed.
| xAI capability | OpenClaw surface | Status |
| -------------------------- | --------------------------------------- | ------------------------------------------------------------------- |
| Chat / Responses | `xai/` model provider | Yes |
| Server-side web search | `web_search` provider `grok` | Yes |
| Server-side X search | `x_search` tool | Yes |
| Server-side code execution | `code_execution` tool | Yes |
| Images | `image_generate` | Yes |
| Videos | `video_generate` | Yes |
| Batch text-to-speech | `messages.tts.provider: "xai"` / `tts` | Yes |
| Streaming TTS | - | Not exposed; OpenClaw's TTS contract returns complete audio buffers |
| Batch speech-to-text | `tools.media.audio` media understanding | Yes |
| Streaming speech-to-text | Voice Call `streaming.provider: "xai"` | Yes |
| Realtime voice | - | Not exposed yet; needs a different session/WebSocket contract |
| Files / batches | Generic model API compatibility only | Not a first-class OpenClaw tool |
OpenClaw uses xAI's REST image/video/TTS/STT APIs for media generation and
batch transcription, xAI's streaming STT WebSocket for live voice-call
transcription, and the Responses API for chat, search, and code-execution
tools.
### Fast-mode mappings
`/fast on` or `agents.defaults.models["xai/"].params.fastMode: true`
rewrites native xAI requests as follows:
| Source model | Fast-mode target |
| ------------- | ------------------ |
| `grok-3` | `grok-3-fast` |
| `grok-3-mini` | `grok-3-mini-fast` |
| `grok-4` | `grok-4-fast` |
| `grok-4-0709` | `grok-4-fast` |
### Legacy compatibility aliases
Legacy aliases normalize to the canonical bundled ids:
| Legacy alias | Canonical id |
| --------------------------------------------------------------------------- | ------------------------------------- |
| `grok-code-fast-1`, `grok-code-fast`, `grok-code-fast-1-0825` | `grok-build-0.1` |
| `grok-4-fast-reasoning` | `grok-4-fast` |
| `grok-4-1-fast-reasoning` | `grok-4-1-fast` |
| `grok-4.20-reasoning`, `grok-4.20-experimental-beta-0304-reasoning` | `grok-4.20-beta-latest-reasoning` |
| `grok-4.20-non-reasoning`, `grok-4.20-experimental-beta-0304-non-reasoning` | `grok-4.20-beta-latest-non-reasoning` |
## Features
The bundled `grok` web-search provider prefers xAI OAuth, then falls back
to `XAI_API_KEY` or a plugin web-search key:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw models auth login --provider xai --method oauth
openclaw config set tools.web.search.provider grok
```
The bundled `xai` plugin registers video generation through the shared
`video_generate` tool.
* Default video model: `xai/grok-imagine-video`
* Modes: text-to-video, image-to-video, reference-image generation, remote
video edit, and remote video extension
* Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`
* Resolutions: `480P`, `720P`
* Duration: 1-15 seconds for generation/image-to-video, 1-10 seconds when
using `reference_image` roles, 2-10 seconds for extension
* Reference-image generation: set `imageRoles` to `reference_image` for
every supplied image; xAI accepts up to 7 such images
* Default operation timeout: 600 seconds unless `video_generate.timeoutMs`
or `agents.defaults.videoGenerationModel.timeoutMs` is set
Local video buffers are not accepted. Use remote `http(s)` URLs for video
edit/extend inputs. Image-to-video accepts local image buffers because
OpenClaw encodes those as data URLs for xAI.
To use xAI as the default video provider:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
agents: {
defaults: {
videoGenerationModel: {
primary: "xai/grok-imagine-video",
},
},
},
}
```
See [Video Generation](/tools/video-generation) for shared tool
parameters, provider selection, and failover behavior.
The bundled `xai` plugin registers image generation through the shared
`image_generate` tool.
* Default image model: `xai/grok-imagine-image`
* Additional model: `xai/grok-imagine-image-quality`
* Modes: text-to-image and reference-image edit
* Reference inputs: one `image` or up to five `images`
* Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
* Resolutions: `1K`, `2K`
* Count: up to 4 images
* Default operation timeout: 600 seconds unless `image_generate.timeoutMs`
or `agents.defaults.imageGenerationModel.timeoutMs` is set
OpenClaw asks xAI for `b64_json` image responses so generated media can be
stored and delivered through the normal channel attachment path. Local
reference images are converted to data URLs; remote `http(s)` references
pass through unchanged.
To use xAI as the default image provider:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
agents: {
defaults: {
imageGenerationModel: {
primary: "xai/grok-imagine-image",
},
},
},
}
```
xAI also documents `quality`, `mask`, `user`, and additional native ratios
such as `1:2`, `2:1`, `9:20`, and `20:9`. OpenClaw forwards only the shared
cross-provider image controls today; these native-only knobs are not
exposed through `image_generate`.
The bundled `xai` plugin registers text-to-speech through the shared `tts`
provider surface.
* Voices: `eve`, `ara`, `rex`, `sal`, `leo`, `una`
* Default voice: `eve`
* Formats: `mp3`, `wav`, `pcm`, `mulaw`, `alaw`
* Language: BCP-47 code or `auto`
* Speed: provider-native speed override
* Native Opus voice-note format is not supported
To use xAI as the default TTS provider:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
messages: {
tts: {
provider: "xai",
providers: {
xai: {
voiceId: "eve",
},
},
},
},
}
```
OpenClaw uses xAI's batch `/v1/tts` endpoint. xAI also offers streaming
TTS over WebSocket, but the OpenClaw speech provider contract currently
expects a complete audio buffer before reply delivery.
The bundled `xai` plugin registers batch speech-to-text through OpenClaw's
media-understanding transcription surface.
* Default model: `grok-stt`
* Endpoint: xAI REST `/v1/stt`
* Input path: multipart audio file upload
* Used wherever inbound audio transcription reads `tools.media.audio`,
including Discord voice-channel segments and channel audio attachments
To force xAI for inbound audio transcription:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
tools: {
media: {
audio: {
models: [
{
type: "provider",
provider: "xai",
model: "grok-stt",
},
],
},
},
},
}
```
Language can be supplied through the shared audio media config or per-call
transcription request. Prompt hints are accepted by the shared OpenClaw
surface, but the xAI REST STT integration forwards only file, model, and
language because those map cleanly to the current public xAI
endpoint.
The bundled `xai` plugin also registers a realtime transcription provider
for live voice-call audio.
* Endpoint: xAI WebSocket `wss://api.x.ai/v1/stt`
* Default encoding: `mulaw`
* Default sample rate: `8000`
* Default endpointing: `800ms`
* Interim transcripts: enabled by default
Voice Call's Twilio media stream sends G.711 mu-law audio frames, so the
xAI provider forwards those frames directly without transcoding:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
plugins: {
entries: {
"voice-call": {
config: {
streaming: {
enabled: true,
provider: "xai",
providers: {
xai: {
apiKey: "${XAI_API_KEY}",
endpointingMs: 800,
language: "en",
},
},
},
},
},
},
},
}
```
Provider-owned config lives under
`plugins.entries.voice-call.config.streaming.providers.xai`. Supported
keys are `apiKey`, `baseUrl`, `sampleRate`, `encoding` (`pcm`, `mulaw`, or
`alaw`), `interimResults`, `endpointingMs`, and `language`.
This streaming provider is for Voice Call's realtime transcription path.
Discord voice records short segments and uses the batch
`tools.media.audio` transcription path instead.
The bundled xAI plugin exposes `x_search` as an OpenClaw tool for
searching X (formerly Twitter) content via Grok.
Config path: `plugins.entries.xai.config.xSearch`
| Key | Type | Default | Description |
| ----------------- | ------- | ----------------------------- | ----------------------------------- |
| `enabled` | boolean | `true` (if key available) | Enable or disable x\_search |
| `model` | string | `grok-4-1-fast-non-reasoning` | Model used for x\_search requests |
| `baseUrl` | string | - | xAI Responses base URL override |
| `inlineCitations` | boolean | - | Include inline citations in results |
| `maxTurns` | number | - | Maximum conversation turns |
| `timeoutSeconds` | number | `30` | Request timeout in seconds |
| `cacheTtlMinutes` | number | `15` | Cache time-to-live in minutes |
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
plugins: {
entries: {
xai: {
config: {
xSearch: {
enabled: true,
model: "grok-4-1-fast-non-reasoning",
baseUrl: "https://api.x.ai/v1",
inlineCitations: true,
},
},
},
},
},
}
```
The bundled xAI plugin exposes `code_execution` as an OpenClaw tool for
remote code execution in xAI's sandbox environment.
Config path: `plugins.entries.xai.config.codeExecution`
| Key | Type | Default | Description |
| ---------------- | ------- | ------------------------- | -------------------------------------- |
| `enabled` | boolean | `true` (if key available) | Enable or disable code execution |
| `model` | string | `grok-4-1-fast` | Model used for code execution requests |
| `maxTurns` | number | - | Maximum conversation turns |
| `timeoutSeconds` | number | `30` | Request timeout in seconds |
This is remote xAI sandbox execution, not local [`exec`](/tools/exec).
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
plugins: {
entries: {
xai: {
config: {
codeExecution: {
enabled: true,
model: "grok-4-1-fast",
},
},
},
},
},
}
```
* xAI auth can use an API key, environment variable, plugin config
fallback, or OAuth with an eligible xAI account. OAuth uses device-code
verification without a localhost callback. xAI decides which accounts
can receive OAuth API tokens, and the consent page may show Grok Build
even though OpenClaw does not require the Grok Build app.
* OpenClaw does not currently expose the xAI multi-agent model family. xAI
serves these models through the Responses API, but they do not accept
the client-side or custom tools used by OpenClaw's shared agent loop.
See the
[xAI multi-agent limitations](https://docs.x.ai/developers/model-capabilities/text/multi-agent#limitations).
* xAI Realtime voice is not registered as an OpenClaw provider yet. It
needs a different bidirectional voice session contract than batch STT
or streaming transcription.
* xAI image `quality`, image `mask`, and extra native-only aspect ratios
are not exposed until the shared `image_generate` tool has
corresponding cross-provider controls.
* OpenClaw applies xAI-specific tool-schema and tool-call compatibility
fixes automatically on the shared runner path.
* Native xAI requests default `tool_stream: true`. Set
`agents.defaults.models["xai/"].params.tool_stream` to `false`
to disable it.
* The bundled xAI wrapper strips unsupported strict tool-schema flags and
reasoning *effort* payload keys before sending native xAI requests. Only
`grok-4.3` / `grok-4.3-*` advertise configurable reasoning effort; all
other reasoning-capable xAI models still request
`include: ["reasoning.encrypted_content"]` so prior encrypted reasoning
can be replayed on follow-up turns.
* `web_search`, `x_search`, and `code_execution` are exposed as OpenClaw
tools. OpenClaw attaches only the specific xAI built-in each tool needs
to that tool's request instead of attaching every native tool to every
chat turn.
* Grok `web_search` reads `plugins.entries.xai.config.webSearch.baseUrl`.
`x_search` reads `plugins.entries.xai.config.xSearch.baseUrl`, then
falls back to the Grok web-search base URL.
* `x_search` and `code_execution` are owned by the bundled xAI plugin
rather than hardcoded into the core model runtime.
* `code_execution` is remote xAI sandbox execution, not local
[`exec`](/tools/exec).
## Live testing
The xAI media paths are covered by unit tests and opt-in live suites. Export
`XAI_API_KEY` in the process environment before running live probes.
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm test extensions/xai
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_TEST_QUIET=1 pnpm test:live -- extensions/xai/xai.live.test.ts
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_TEST_QUIET=1 OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS=xai pnpm test:live -- test/image-generation.runtime.live.test.ts
```
The provider-specific live file synthesizes normal TTS, telephony-friendly PCM
TTS, transcribes audio through xAI batch STT, streams the same PCM through xAI
realtime STT, generates text-to-image output, and edits a reference image.
The shared image live file verifies the same xAI provider through OpenClaw's
runtime selection, fallback, normalization, and media attachment path.
## Related
Choosing providers, model refs, and failover behavior.
Shared video tool parameters and provider selection.
The broader provider overview.
Common issues and fixes.