xAI

The bundled grok web-search provider prefers xAI OAuth, then falls back to XAI_API_KEY or a plugin web-search key:

openclaw models auth login --provider xai --method oauthopenclaw config set tools.web.search.provider grok

The bundled xai plugin registers video generation through the shared video_generate tool.

• Default model: xai/grok-imagine-video
• Additional model: xai/grok-imagine-video-1.5
• Classic modes: text-to-video, image-to-video, reference-image generation, remote video edit, and remote video extension
• Video 1.5 mode: image-to-video only, with exactly one first-frame image
• Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3; classic and Video 1.5 image-to-video inherit the source image ratio when omitted
• Resolutions: classic 480P/720P; Video 1.5 also supports 1080P; all generation modes default to 480P
• Duration: 1-15 seconds for generation/image-to-video, 1-10 seconds when using classic reference_image roles, 2-10 seconds for classic extension
• Reference-image generation: set imageRoles to reference_image for every supplied image; xAI accepts up to 7 such images
• Video edit/extend inherit the input video's aspect ratio and resolution; those operations do not accept geometry overrides
• Default operation timeout: 600 seconds unless video_generate.timeoutMs or agents.defaults.mediaModels.video.timeoutMs is set

Video 1.5 also recognizes xAI's grok-imagine-video-1.5-preview and grok-imagine-video-1.5-2026-05-30 identifiers. OpenClaw forwards the selected identifier unchanged, but applies the same image-only validation.

To use xAI as the default video provider:

{  agents: {    defaults: {      mediaModels: {        video: {          primary: "xai/grok-imagine-video",        },      },    },  },}

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 three images
• Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 19.5:9, 9:19.5, 20:9, 9:20
• Resolutions: 1K, 2K
• Count: up to 4 images
• Default operation timeout: 600 seconds unless image_generate.timeoutMs or agents.defaults.mediaModels.image.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:

{  agents: {    defaults: {      mediaModels: {        image: {          primary: "xai/grok-imagine-image",        },      },    },  },}

The bundled xai plugin registers text-to-speech through the shared tts provider surface.

• Voices: authenticated live catalog from xAI; list it with openclaw infer tts voices --provider xai
• Offline fallback voices: ara, eve, leo, rex, sal
• Default voice: eve
• Account custom voice IDs are forwarded even when they are absent from the built-in catalog response
• 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:

{  tts: {    provider: "xai",    providers: {      xai: {        voiceId: "eve",      },    },  },}

The bundled xai plugin registers batch speech-to-text through OpenClaw's media-understanding transcription surface.

• Endpoint: xAI REST /v1/stt
• Input path: multipart audio file upload
• Model selection: xAI chooses the transcription model internally; the endpoint has no model selector
• 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:

{  tools: {    media: {      models: [        {          type: "provider",          provider: "xai",          capabilities: ["audio"],        },      ],      audio: {        enabled: true,      },    },  },}

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 and language because those map to the current public xAI endpoint.

Valid empty transcripts are skipped, and OpenClaw tries any configured fallback. Malformed responses and HTTP failures remain errors.

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:

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

The bundled xai plugin registers Grok Voice Agent realtime sessions for Talk mode through the shared registerRealtimeVoiceProvider contract.

• Endpoint: wss://api.x.ai/v1/realtime?model=<voice-model>
• Default model: grok-voice-latest
• Default voice: eve
• Transport: gateway-relay (iOS, Android, and Control UI relay paths)
• Audio: PCM16 24 kHz or G.711 µ-law 8 kHz
• Barge-in: xAI server VAD interrupts the response; OpenClaw clears queued playback and truncates unplayed provider history

Configure Talk on the Gateway:

{  talk: {    realtime: {      provider: "xai",      mode: "realtime",      transport: "gateway-relay",      brain: "agent-consult",      providers: {        xai: {          model: "grok-voice-latest",          voice: "eve",          // Opt in only if provider-side session replay is acceptable.          sessionResumption: false,        },      },    },  },  env: { vars: { XAI_API_KEY: "xai-..." } },}

Provider-owned config also resolves from plugins.entries.voice-call.config.realtime.providers.xai when Voice Call or shared realtime selectors reuse the same provider map. Supported keys are apiKey, baseUrl, model, voice, vadThreshold, silenceDurationMs, prefixPaddingMs, reasoningEffort, and sessionResumption. reasoningEffort accepts only high or none, matching the xAI Voice Agent API.

xAI's server VAD always creates responses and handles audio interruption. Use consultRouting: "provider-direct"; forced transcript routing and disabling input-audio interruption are not supported by the xAI Voice Agent protocol.

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

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true,            model: "grok-4.3",            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

{  plugins: {    entries: {      xai: {        config: {          codeExecution: {            enabled: true,            model: "grok-4.3",          },        },      },    },  },}

Native api.x.ai Responses routes use xAI's server-side /responses/compact endpoint by default for manual /compact and threshold-driven preflight compaction. The session keeps its OpenClaw transcript unchanged and stores xAI's opaque checkpoint for the next request. Completion notices report the provider's before and after token counts.

Disable the endpoint for one model with:

{  agents: {    defaults: {      models: {        "xai/grok-4.5": {          params: { responsesCompactEndpoint: false },        },      },    },  },}

Other Responses-compatible providers can opt in with params.responsesCompactEndpoint: true; non-Responses routes ignore the setting. OpenAI's native Responses API does not need this option because its context_management compaction is already managed by responsesServerCompaction.

Endpoint failures fall back to OpenClaw's client-side summarization. Overflow recovery never calls the endpoint because xAI requires the input to fit the model context window before compaction.

• 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.
• xAI Realtime voice currently exposes gateway-relay Talk transport only. Browser-owned provider WebSocket sessions are not wired in the Control UI yet.
• 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 https://api.x.ai/v1 Responses requests keep tool images attached to their tool results. On compatibility routes (including Grok OAuth), image-capable models receive a labeled user image message immediately after each consecutive tool-result group. Parallel results stay together, and later turns preserve the historical image position for prompt caching. Compaction establishes a new history prefix and result numbering.
• 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 contains-count schema bounds and unsupported reasoning effort payload keys before sending native xAI requests. Grok 4.6 supports low, medium, high, and xhigh effort (default high). Grok 4.5 supports low, medium, and high effort (default high). Grok 4.3 supports none, low, medium, and high effort (default low). Other reasoning-capable xAI models do not expose a configurable effort control, but 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.