Use xAI Grok Models in OpenClaw

OpenClaw includes a built-in xai provider plugin for Grok models. Grok OAuth, paired with an eligible SuperGrok or X Premium subscription, is the recommended route. Gateway, config, routing, and tools all remain local; only Grok requests are sent to xAI's API.

An xAI API key or the Grok Build app is not needed for OAuth. Because OpenClaw relies on xAI's shared OAuth client, xAI might still display Grok Build on the consent screen.

Setup

New install

Start onboarding with daemon install, then choose xAI/Grok OAuth during the model/auth step:

openclaw onboard --install-daemon

For a VPS or SSH session, pick xAI OAuth directly; it relies on device-code verification and skips the localhost callback requirement:

openclaw onboard --install-daemon --auth-choice xai-oauth

Existing install

Only sign in to xAI; full onboarding does not need to be rerun just to link Grok:

openclaw models auth login --provider xai --method oauth

When no primary model exists yet, OAuth setup picks xai/auto. The plugin pulls that stable ref from xAI's authenticated model catalog and remote default, so future xAI default shifts won't force an OpenClaw update. An existing primary is kept intact; opt in explicitly when desired:

openclaw models set xai/auto

Rerun full onboarding only when you deliberately want to alter Gateway, daemon, channel, workspace, or other configuration choices.

API-key path

API-key setup remains available for xAI Console keys and for media surfaces that require key-backed provider config. It keeps Grok 4.3 as the regional-safe setup default:

openclaw models auth login --provider xai --method api-key
export XAI_API_KEY=xai-...

Pick a model

{
  agents: { defaults: { model: { primary: "xai/auto" } } },
}

Note

The bundled xAI transport in OpenClaw is the xAI Responses API. The same credential from openclaw models auth login --provider xai --method oauth or --method api-key also drives web_search (provider id grok), x_search, code_execution, speech/transcription, and xAI image/video generation. If an xAI key is saved under plugins.entries.xai.config.webSearch.apiKey, the bundled xAI model provider also uses it as a fallback.

OAuth troubleshooting

• For SSH, Docker, VPS, or other remote setups, go with openclaw models auth login --provider xai --method oauth; it uses device-code verification rather than a localhost callback.

• If sign-in succeeds but Grok isn't the default model, execute openclaw models set xai/auto. OAuth login leaves an existing primary model untouched unless you explicitly change it.

• Review saved xAI auth profiles:

  openclaw models auth list --provider xai
  openclaw models status
  

• xAI controls which accounts are allowed to receive OAuth API tokens. If an account isn't eligible, fall back to the API-key path or verify the subscription on xAI's end.

Tip

When signing in from SSH, Docker, or a VPS, use xai-oauth. OpenClaw displays a URL and short code; complete sign-in in any local browser while the remote process polls xAI for the finished token exchange.

Built-in catalog

Selectable ids appear 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 and moving aliases.

Tip

To track xAI's authenticated OAuth default, use xai/auto, or stay pinned by selecting a concrete id like xai/grok-4.6. API-key setup defaults to Grok 4.3 as the regional-safe choice; Grok 4.6, Grok 4.5, grok-build-0.1, and both dated Grok 4.20 variants remain selectable.

Catalog context and token-cost metadata follows xAI's live model pages and pricing page. When a request crosses xAI's documented 200k-token long-context threshold, higher rates apply: for Grok 4.5 and Grok 4.6, input, cached-input, and output rates double. OpenClaw's flat catalog cost fields store the short-context rates. The current Grok Build coding agent runs on Grok 4.6. The historical OpenClaw grok-build-latest compatibility alias stays pinned to Grok 4.5.

Feature coverage

The bundled plugin maps supported xAI APIs onto OpenClaw's shared provider and tool contracts. Capabilities that don't fit the shared contract are listed below or under known limits.

Note

For media creation and batch transcription, OpenClaw calls xAI's REST image, video, TTS, and STT endpoints. Live voice-call transcription relies on xAI's streaming STT WebSocket, while Talk realtime sessions use the Grok Voice Agent WebSocket. Chat, search, and code-execution tools go through the Responses API.

Legacy fast-mode compatibility

/fast on or agents.defaults.models["xai/<model>"].params.fastMode: true still rewrites older xAI configurations as follows. These target ids are kept only for compatibility; use current selectable models for new configurations.

Legacy compatibility and moving aliases

Older aliases normalize as follows:

The dated 0309 ids are the selectable catalog entries. OpenClaw sends all other current Grok 4.20 aliases verbatim so xAI retains control of stable, latest, beta, experimental, and dated alias semantics. The global grok-latest alias is also preserved verbatim.

xAI retired the following exact ids. OpenClaw keeps them as hidden compatibility rows for shipped configurations, with the limits and pricing of their current redirect targets:

openclaw doctor --fix updates persisted xAI server-tool defaults and the retired quality image slug, removes stale generated catalog rows, and repairs stale context metadata on active 4.20 rows. It does not pin active 4.20 beta-latest aliases to a dated snapshot.

Features

Warning

x_search and code_execution run on xAI's servers. xAI bills $5 per 1,000 tool calls, plus the model's input and output tokens. With each tool's enabled setting omitted, OpenClaw exposes it only for an active xAI model. A known non-xAI model provider requires an explicit per-tool enabled: true; a missing or unresolved provider fails closed. xAI auth is always required, and enabled: false disables the tool for every provider.

Web search

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 oauth
openclaw config set tools.web.search.provider grok

Video generation

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

Warning

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.

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",
        },
      },
    },
  },
}

Note

See Video Generation for shared tool parameters, provider selection, and failover behavior.

Image generation

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",
        },
      },
    },
  },
}

Note

xAI also documents quality, mask, user, and an auto aspect ratio. OpenClaw forwards only the shared cross-provider image controls today; these native-only knobs are not exposed through image_generate.

Text-to-speech

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

• Voices: xAI serves a live, authenticated catalog; request it with openclaw infer tts voices --provider xai
• Offline fallback voices: ara, eve, leo, rex, sal
• Default voice: eve
• Account custom voice IDs pass through even when the built-in catalog response omits them
• Formats: mp3, wav, pcm, mulaw, alaw
• Language: BCP-47 code or auto
• Speed: provider-native speed override
• Native Opus voice-note format is unsupported

To make xAI the default TTS provider:

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

Note

Buffered synthesis in OpenClaw relies on xAI's batch /v1/tts endpoint, while authenticated /v1/tts/voices catalog discovery and streaming synthesis use native wss://api.x.ai/v1/tts. Streaming only works against the native api.x.ai host, so custom baseUrl values get rejected on that route. Existing language, voice, codec, and speed settings carry over; sample rate and bit rate fall back to xAI defaults. Audio-file synthesis respects every configured codec. For voice-note targets, MP3 is used in both streaming and buffered fallback because xAI's raw codecs lack codec/rate metadata. The stream transmits text.delta followed by text.done, accepts audio.delta, audio.done, or error, and maintains an idle timeoutMs that refreshes per audio chunk. It operates independently of realtime voice sessions. Refer to xAI's Streaming TTS API contract.

Speech-to-text

The bundled xai plugin exposes 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 picks the transcription model internally; the endpoint offers 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 arrives via the shared audio media config or a 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 align with the current public xAI endpoint.

Streaming speech-to-text

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 delivers G.711 mu-law audio frames, so the xAI provider relays those frames as-is 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.

Note

This streaming provider serves Voice Call's realtime transcription path. Discord voice records short segments and uses the batch tools.media.audio transcription path instead.

Realtime voice (Talk)

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-level configuration is also pulled from plugins.entries.voice-call.config.realtime.providers.xai when Voice Call or shared realtime selectors point at the same provider map. The accepted keys are apiKey, baseUrl, model, voice, vadThreshold, silenceDurationMs, prefixPaddingMs, reasoningEffort, and sessionResumption. Only high or none are valid values for reasoningEffort, which aligns with the xAI Voice Agent API.

With xAI's server VAD, responses are always generated and audio interruption is managed automatically. Make use of consultRouting: "provider-direct"; the xAI Voice Agent protocol does not support forced transcript routing or disabling input-audio interruption.

Note

Realtime voice can be authenticated through xAI OAuth or XAI_API_KEY. Browser-owned WebRTC is not yet available on this provider surface; rely on gateway-relay Talk for native nodes or the Control UI relay path.

Note

The default for sessionResumption is false. Once set to true, OpenClaw instructs xAI to preserve enough session state for resuming the same conversation after a reconnect, then reconnects using the returned conversation id. Keep it off when provider-side replay/retention is not acceptable; interrupted sockets then fail closed rather than silently initiating a fresh conversation.

x_search configuration

The bundled xAI plugin provides x_search as an OpenClaw tool for searching X (formerly Twitter) content through 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,
          },
        },
      },
    },
  },
}

Code execution configuration

The bundled xAI plugin exposes code_execution as an OpenClaw tool for remote code execution within xAI's sandbox environment.

Config path: plugins.entries.xai.config.codeExecution

Note

This executes in xAI's remote sandbox, not locally via exec.

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

Context compaction

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 OpenClaw transcript for the session stays unchanged, while xAI's opaque checkpoint is stored for the next request. Completion notices report the provider's before and after token counts.

To disable the endpoint for a single model, use:

{
  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 require this option because its context_management compaction is already handled by responsesServerCompaction.

When the endpoint fails, OpenClaw's client-side summarization takes over. Overflow recovery never calls the endpoint, since xAI requires the input to fit the model context window before compaction.

Known limits

• Authentication for xAI can come from an API key, environment variable, plugin config fallback, or OAuth with an eligible xAI account. OAuth uses device-code verification with no localhost callback. xAI determines which accounts can receive OAuth API tokens, and the consent page may display Grok Build even though OpenClaw does not require the Grok Build app.
• The xAI multi-agent model family is not currently exposed by OpenClaw. 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.
• Gateway-relay Talk transport is the only option for xAI Realtime voice right now. Browser-owned provider WebSocket sessions are not yet connected in the Control UI.
• xAI image quality, image mask, and extra native-only aspect ratios are not exposed until the shared image_generate tool gains matching cross-provider controls.

Advanced notes

• On the shared runner path, OpenClaw automatically applies xAI-specific compatibility fixes for tool schemas and tool calls.
• Native xAI requests default to tool_stream: true. To turn this off, set agents.defaults.models["xai/<model>"].params.tool_stream to false.
• Before sending native xAI requests, the bundled xAI wrapper removes unsupported contains-count schema bounds and unsupported reasoning effort payload keys. Grok 4.6 accepts low, medium, high, and xhigh effort, with high as the default. Grok 4.5 accepts low, medium, and high effort, defaulting to high. Grok 4.3 accepts none, low, medium, and high effort, defaulting to low. Other reasoning-capable xAI models do not offer a configurable effort control, yet they still request include: ["reasoning.encrypted_content"] so that previously encrypted reasoning can be replayed on subsequent turns.
• web_search, x_search, and code_execution are available as OpenClaw tools. Rather than attaching every native tool to each chat turn, OpenClaw attaches only the specific xAI built-in that a given tool requires to that tool's request.
• 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.
• The bundled xAI plugin owns x_search and code_execution; they are not hardcoded into the core model runtime.
• code_execution refers to remote xAI sandbox execution, not local exec.

Live testing

Unit tests and opt-in live suites cover the xAI media paths. Before running live probes, export XAI_API_KEY in the process environment.

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_XAI_VIDEO=1 pnpm test:live -- extensions/xai/xai.live.test.ts -t "classic Grok Imagine"
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_XAI_VIDEO=1 pnpm test:live -- extensions/xai/xai.live.test.ts -t "Grok Imagine Video 1.5"
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_TEST_QUIET=1 pnpm test:live -- extensions/xai/x-search.live.test.ts
OPENCLAW_LIVE_GATEWAY_MODELS="xai/grok-4.6,xai/grok-4.5,xai/grok-build-0.1,xai/grok-4.3,xai/grok-4.20-0309-reasoning,xai/grok-4.20-0309-non-reasoning" OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0 OPENCLAW_LIVE_GATEWAY_SMOKE=0 pnpm test:live -- src/gateway/gateway-models.profiles.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. The opt-in Video 1.5 case submits one generated first-frame image at 1080P and verifies the completed video download.

Related

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