Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw ships a bundled xai provider plugin for Grok models.

​
Getting started

1

Create an API key

Create an API key in the xAI console.
2

Set your API key

Set XAI_API_KEY, or run:
openclaw onboard --auth-choice xai-api-key
3

Pick a model

{
  agents: { defaults: { model: { primary: "xai/grok-4.3" } } },
}
OpenClaw uses the xAI Responses API as the bundled xAI transport. The same XAI_API_KEY can also power Grok-backed web_search, first-class x_search, and remote code_execution. If you store an xAI key under plugins.entries.xai.config.webSearch.apiKey, the bundled xAI model provider reuses that key as a fallback too. Set plugins.entries.xai.config.webSearch.baseUrl to route Grok web_search and, by default, x_search through an operator xAI Responses proxy. code_execution tuning lives under plugins.entries.xai.config.codeExecution.

​
Built-in catalog

OpenClaw includes these xAI model families out of the box:
FamilyModel ids
Grok 3grok-3, grok-3-fast, grok-3-mini, grok-3-mini-fast
Grok 4.3grok-4.3
Grok 4grok-4, grok-4-0709
Grok 4 Fastgrok-4-fast, grok-4-fast-non-reasoning
Grok 4.1 Fastgrok-4-1-fast, grok-4-1-fast-non-reasoning
Grok 4.20 Betagrok-4.20-beta-latest-reasoning, grok-4.20-beta-latest-non-reasoning
Grok Codegrok-code-fast-1
The plugin also forward-resolves newer grok-4* and grok-code-fast* ids when they follow the same API shape.
grok-4.3, grok-4-fast, grok-4-1-fast, and the grok-4.20-beta-* variants are the current image-capable Grok refs in the bundled catalog.

​
OpenClaw feature coverage

The bundled plugin maps xAI’s current public API surface onto OpenClaw’s shared provider and tool contracts. Capabilities that don’t fit the shared contract (for example streaming TTS and realtime voice) are not exposed — see the table below.
xAI capabilityOpenClaw surfaceStatus
Chat / Responsesxai/<model> model providerYes
Server-side web searchweb_search provider grokYes
Server-side X searchx_search toolYes
Server-side code executioncode_execution toolYes
Imagesimage_generateYes
Videosvideo_generateYes
Batch text-to-speechmessages.tts.provider: "xai" / ttsYes
Streaming TTS—Not exposed; OpenClaw’s TTS contract returns complete audio buffers
Batch speech-to-texttools.media.audio / media understandingYes
Streaming speech-to-textVoice Call streaming.provider: "xai"Yes
Realtime voice—Not exposed yet; different session/WebSocket contract
Files / batchesGeneric model API compatibility onlyNot a first-class OpenClaw tool
OpenClaw uses xAI’s REST image/video/TTS/STT APIs for media generation, speech, and batch transcription, xAI’s streaming STT WebSocket for live voice-call transcription, and the Responses API for model, search, and code-execution tools. Features that need different OpenClaw contracts, such as Realtime voice sessions, are documented here as upstream capabilities rather than hidden plugin behavior.

​
Fast-mode mappings

/fast on or agents.defaults.models["xai/<model>"].params.fastMode: true rewrites native xAI requests as follows:
Source modelFast-mode target
grok-3grok-3-fast
grok-3-minigrok-3-mini-fast
grok-4grok-4-fast
grok-4-0709grok-4-fast

​
Legacy compatibility aliases

Legacy aliases still normalize to the canonical bundled ids:
Legacy aliasCanonical id
grok-4-fast-reasoninggrok-4-fast
grok-4-1-fast-reasoninggrok-4-1-fast
grok-4.20-reasoninggrok-4.20-beta-latest-reasoning
grok-4.20-non-reasoninggrok-4.20-beta-latest-non-reasoning

​
Features

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
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 can encode those as data URLs for xAI.
To use xAI as the default video provider:
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "xai/grok-imagine-video",
      },
    },
  },
}
See 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-pro
  • 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
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 are passed through.To use xAI as the default image provider:
{
  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; unsupported native-only knobs are intentionally 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:
{
  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
  • Supported by OpenClaw wherever inbound audio transcription uses tools.media.audio, including Discord voice-channel segments and channel audio attachments
To force xAI for inbound audio transcription:
{
  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 only forwards 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 µ-law audio frames, so the xAI provider can forward those frames directly without transcoding:
{
  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 currently 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
KeyTypeDefaultDescription
enabledboolean—Enable or disable x_search
modelstringgrok-4-1-fastModel used for x_search requests
baseUrlstring—xAI Responses base URL override
inlineCitationsboolean—Include inline citations in results
maxTurnsnumber—Maximum conversation turns
timeoutSecondsnumber—Request timeout in seconds
cacheTtlMinutesnumber—Cache time-to-live in minutes
{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true,
            model: "grok-4-1-fast",
            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
KeyTypeDefaultDescription
enabledbooleantrue (if key available)Enable or disable code execution
modelstringgrok-4-1-fastModel used for code execution requests
maxTurnsnumber—Maximum conversation turns
timeoutSecondsnumber—Request timeout in seconds
This is remote xAI sandbox execution, not local exec.
{
  plugins: {
    entries: {
      xai: {
        config: {
          codeExecution: {
            enabled: true,
            model: "grok-4-1-fast",
          },
        },
      },
    },
  },
}
  • Auth is API-key only today. There is no xAI OAuth or device-code flow in OpenClaw yet.
  • grok-4.20-multi-agent-experimental-beta-0304 is not supported on the normal xAI provider path because it requires a different upstream API surface than the standard OpenClaw xAI transport.
  • 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/<model>"].params.tool_stream to false to disable it.
  • The bundled xAI wrapper strips unsupported strict tool-schema flags and reasoning payload keys before sending native xAI requests.
  • web_search, x_search, and code_execution are exposed as OpenClaw tools. OpenClaw enables the specific xAI built-in it needs inside each tool request instead of attaching all native tools 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.

​
Live testing

The xAI media paths are covered by unit tests and opt-in live suites. The live commands load secrets from your login shell, including ~/.profile, before probing XAI_API_KEY. 
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.

Model selection

Choosing providers, model refs, and failover behavior.

Video generation

Shared video tool parameters and provider selection.

All providers

The broader provider overview.

Troubleshooting

Common issues and fixes.