Connect xAI Grok Models to OpenClaw via OAuth

Set up the bundled xai provider plugin to use Grok models in OpenClaw through Grok OAuth with a SuperGrok or X Premium subscription. Covers new installs, existing installs, and VPS or SSH authentication.

Read this when

  • You want to use Grok models in OpenClaw
  • You are configuring xAI auth or model ids

A bundled xai provider plugin for Grok models is included with OpenClaw. The suggested route is Grok OAuth paired with an eligible SuperGrok or X Premium subscription. Config, routing, tools, and the Gateway all stay local; only Grok requests travel to xAI's API.

No xAI API key and no Grok Build app are needed for OAuth. Grok Build may still appear on xAI's consent screen, since OpenClaw relies on xAI's shared OAuth client.

Setup

New install

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

openclaw onboard --install-daemon

When running on a VPS or over SSH, pick xAI OAuth directly; verification happens through a device code, so no localhost callback is required:

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

Existing install

Authenticate against xAI alone; there is no need to rerun full onboarding just to hook up Grok:

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

If no primary model exists yet, OAuth setup picks the curated default, xai/grok-4.7. Discovery performed after authentication refreshes the available model rows while that default stays put. Any existing primary is kept; opt in explicitly when you want a change:

openclaw models set xai/grok-4.7

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

API-key path

API-key setup remains available for xAI Console keys and for media surfaces that require key-backed provider config. The same Grok 4.7 setup default applies:

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

Pick a model

{
  agents: { defaults: { model: { primary: "xai/grok-4.7" } } },
}

Note

The xAI Responses API serves as the bundled xAI transport inside OpenClaw. One credential, whether 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. Should you store an xAI key under plugins.entries.xai.config.webSearch.apiKey, the bundled xAI model provider falls back to it as well.

openclaw status --usage, /status, and the Control UI usage cards report SuperGrok quota whenever the xAI provider is signed in through OAuth. OpenClaw retrieves the Grok billing window tied to that subscription and surfaces its reset time through the usual provider-usage interface. If xAI leaves out an included-usage percent on a weekly or monthly billing period that is otherwise valid, OpenClaw states that included usage was omitted rather than fabricating a percentage or displaying a generic "No usage data". On-demand pay-as-you-go counters do not count as SuperGrok subscription quota. Setups that use only an API key are deliberately excluded from SuperGrok usage display, because xAI Console API credits and SuperGrok subscription quota are billed separately.

OAuth troubleshooting

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

  • If an earlier OAuth login left xAI pointed at the API-key endpoint or catalog, rerun openclaw models auth login --provider xai --method oauth. A successful login refreshes the subscription catalog and proxy route from your account. Your primary model and fallbacks are preserved.

  • If sign-in succeeds but Grok is not the default model, run openclaw models set xai/grok-4.7. OAuth login keeps an existing primary model unless you change it explicitly.

  • Under OAuth, thinking levels mirror the reasoning efforts reported by your account's model listing. When a listed model cannot turn reasoning off, off is not offered. If the picker shows effort levels for a model but --thinking rejects them, the login predates this behavior: rerun openclaw models auth login --provider xai --method oauth to refresh the saved model rows.

  • Inspect saved xAI auth profiles:

    openclaw models auth list --provider xai
    openclaw models status
    
  • Which accounts can receive OAuth API tokens is xAI's decision. For an account that is not eligible, use the API-key path or check the subscription on xAI's side.

  • If the Gateway log shows xai: OAuth profile "..." could not be resolved, credential preparation failed, for example because a refresh token expired or was revoked. The warning carries the redacted cause and the resulting live catalog origin, or reports that no live catalog was returned. An existing API key can still supply the API catalog; OAuth-only models stay unavailable. Run the warning's sign-in command on the Gateway host; it targets the catalog's agent and saved profile. This covers catalog discovery only, not evidence of an inference request or an API charge.

Existing xai/auto selections on the native xAI API and Grok subscription routes have been retired. Run openclaw doctor --fix to swap affected config and session selections for xai/grok-4.7. Doctor keeps account pins and fallbacks, and leaves custom endpoints untouched. For a pinned session, an unavailable account or a disallowed successor leaves the selection as is, with a diagnostic explaining the required action. A shared alias is moved by Doctor only when the applicable accounts and routes agree on its successor. You may also pick a permitted concrete model yourself.

To manage a Grok subscription token by hand, set models.providers.xai.auth to "token" and models.providers.xai.baseUrl to https://cli-chat-proxy.grok.com/v1. Model discovery relies on the subscription catalog and keeps token authentication; if the token is unavailable, discovery does not fall back to the Console API. Tokens using the default or native xAI API endpoint keep using the API catalog. For automatic token refresh, prefer OAuth login. Resolved environment-backed tokens also work in standalone model commands with no Gateway running.

Tip

Reach for xai-oauth when signing in from SSH, Docker, or a VPS. OpenClaw prints 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 in model pickers. Older Grok 3, Grok 4, Grok 4 Fast, Grok 4.1 Fast, and Grok Code ids are still resolved by the plugin for existing configs; see legacy compatibility and moving aliases.

FamilyModel ids
Grok 4.7grok-4.7 (alias: grok-4.7-latest)
Grok 4.6grok-4.6
Grok 4.5grok-4.5 (aliases: grok-4.5-latest, grok-build-latest)
Grok Build 0.1grok-build-0.1
Grok 4.3grok-4.3 (aliases: grok-4.3-latest, grok-latest)
Grok 4.20grok-4.20-0309-reasoning, grok-4.20-0309-non-reasoning

Tip

Both OAuth and API-key setup treat xai/grok-4.7 as the curated default. Grok 4.6, Grok 4.5, grok-build-0.1, Grok 4.3, and both dated Grok 4.20 variants stay selectable.

The curated list lives in the plugin manifest. With ordinary API-key setup, that inventory stays in the plugin rather than being copied into your configuration; models.mode: "replace" still receives the curated rows. Explicit model rows are left as they are. OAuth login keeps its authenticated account catalog.

Catalog context and token-cost metadata track xAI's live model pages and pricing page. Requests that cross xAI's documented 200k-token long-context threshold draw higher rates: for Grok 4.5, Grok 4.6, and Grok 4.7, input, cached-input, and output rates are doubled. OpenClaw's flat catalog cost fields capture the short-context rates. The current Grok Build coding agent runs on Grok 4.7. The historical OpenClaw grok-build-latest compatibility alias stays pinned to Grok 4.5.

Aliases that are supported but not curated keep their reasoning, input, and token-limit metadata without being added to the published inventory. Pricing for them stays unknown, stored as zero until the manifest lists them. A zero means the estimate is unavailable; it does not mean the provider charges nothing.

Thinking levels are governed by xAI's documented release rule, not by a fixed model list. low, medium, and high are accepted by Grok 4.5 and later; Grok 4.6 and later adds xhigh. high is the default, and reasoning cannot be disabled. A newer release id like grok-4.8, its -latest alias, or a dated snapshot receives these levels and image input before the manifest lists it. Variant ids such as -fast keep reasoning effort off.

Feature coverage

Supported xAI APIs are mapped by the bundled plugin onto OpenClaw's shared provider and tool contracts. Capabilities that do not fit the shared contract appear below or under known limits.

xAI capabilityOpenClaw surfaceStatus
Chat / Responsesxai/<model> model providerYes
Context compaction/compact and threshold compactionYes via /v1/responses/compact
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-speechtts.provider: "xai" / ttsYes
Streaming TTStextToSpeechStreamYes via wss://api.x.ai/v1/tts (not realtime voice)
Batch speech-to-texttools.media.audio media understandingYes
Streaming speech-to-textVoice Call streaming.provider: "xai"Yes
Realtime voiceTalk talk.realtime.provider: "xai"Yes; gateway-relay for native Talk nodes
Files / batchesGeneric model API compatibility onlyNot a first-class OpenClaw tool

Note

For media generation and batch transcription OpenClaw relies on xAI's REST image/video/TTS/STT APIs, for live voice-call transcription it uses xAI's streaming STT WebSocket, for Talk realtime sessions it uses xAI's Grok Voice Agent WebSocket, and for chat, search, and code-execution tools it uses the Responses API.

Legacy fast-mode compatibility

Older xAI configurations are still rewritten by /fast on or agents.defaults.models["xai/<model>"].params.fastMode: true as shown below. These target ids exist only for compatibility; pick current selectable models when creating new configurations.

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 and moving aliases

Legacy aliases are normalized as follows:

Legacy aliasNormalized id
grok-code-fast-1, grok-code-fast, grok-code-fast-1-0825grok-build-0.1

The dated 0309 ids are the catalog entries you can select. Every other current Grok 4.20 alias is sent verbatim by OpenClaw, which leaves xAI in control of the semantics for stable, latest, beta, experimental, and dated aliases. The global grok-latest alias is likewise passed through unchanged.

The exact ids below were retired by xAI. Normalization and transport paths are retained in existing configurations; uncurated model names are priced as unknown:

Retired idsCurrent behavior
grok-4-1-fast-reasoning, grok-4-fast-reasoning, grok-4-0709Grok 4.3 with low reasoning
grok-4-1-fast-non-reasoning, grok-4-fast-non-reasoning, grok-3Grok 4.3 with reasoning disabled
grok-code-fast-1Grok Build 0.1
grok-imagine-image-proGrok Imagine Image Quality

Persisted xAI server-tool defaults and the retired quality image slug are updated by openclaw doctor --fix, which also drops stale generated catalog rows and fixes stale context metadata on active 4.20 rows. Active 4.20 beta-latest aliases are not pinned to a dated snapshot by this update.

Features

When web_search, x_search, and code_execution are unconfigured, requests fall back to Grok 4.7. Existing installations that leave the tool model setting out are covered by this too. An explicit tool model still takes precedence; the Grok 4.3 examples below are overrides.

Warning

x_search and code_execution execute on servers operated by xAI. Charges from xAI are $5 per 1,000 tool calls, on top of the model's input and output tokens. When a tool's enabled setting is left out, OpenClaw offers that tool only while an xAI model is active. For a known non-xAI model provider, an explicit per-tool enabled: true is required; if the provider is missing or cannot be resolved, the request is blocked. xAI authentication is required in all cases, and enabled: false turns the tool off for every provider.

For web search, the bundled grok provider tries xAI OAuth first, and if that is unavailable it falls back to XAI_API_KEY or to a plugin web-search key:

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

Video generation

Video generation is registered by the bundled xai plugin through the shared video_generate tool.

  • Model used by default: xai/grok-imagine-video
  • Second model available: 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, and it takes exactly one first-frame image
  • Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3; for classic and Video 1.5 image-to-video, omitting the ratio inherits the source image's ratio
  • Resolutions: 480P/720P for classic; Video 1.5 additionally accepts 1080P; every generation mode defaults to 480P
  • Duration: 1-15 seconds for generation and image-to-video, 1-10 seconds with classic reference_image roles, 2-10 seconds for classic extension
  • Reference-image generation: for each image you supply, set imageRoles to reference_image; xAI accepts a maximum of 7 such images
  • Video edit and extend take the aspect ratio and resolution from the input video; geometry overrides are not accepted by those operations
  • Operation timeout defaults to 600 seconds, unless video_generate.timeoutMs or agents.defaults.mediaModels.video.timeoutMs is set

Warning

Local video buffers are rejected. Video edit and extend inputs must be remote http(s) URLs. Image-to-video does accept local image buffers, since OpenClaw encodes them as data URLs for xAI.

xAI's grok-imagine-video-1.5-preview and grok-imagine-video-1.5-2026-05-30 identifiers are also recognized by Video 1.5. OpenClaw passes the chosen identifier through without changes, though the same image-only validation still applies.

To make xAI your default video provider:

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

Note

Shared tool parameters, provider selection, and failover behavior are described in Video Generation.

Image generation

Image generation is registered by the bundled xai plugin through the shared image_generate tool.

  • Image model used by default: xai/grok-imagine-image
  • Other models available: xai/grok-imagine-image-2.0, xai/grok-imagine-image-quality
  • Modes: text-to-image and reference-image edit
  • Reference inputs: a single image or as many as 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: a maximum of 4 images
  • Operation timeout defaults to 600 seconds, unless image_generate.timeoutMs or agents.defaults.mediaModels.image.timeoutMs is set

OpenClaw requests b64_json image responses from xAI, which lets generated media be stored and delivered via the standard channel attachment path. Local reference images get converted into data URLs, while remote http(s) references are passed through as-is.

To point at a private image endpoint you control, set models.providers.xai.baseUrl and models.providers.xai.request.allowPrivateNetwork: true. Without that opt-in, private endpoints stay blocked. The endpoint opt-in cannot be used by returned image URLs or their redirects to reach other private origins.

Pick xai/grok-imagine-image-2.0 explicitly to get Image 2.0; the default is still xai/grok-imagine-image. Provider-qualified image model IDs given explicitly are passed through to xAI, including IDs that aren't in OpenClaw's catalog yet. If a bare model override is unknown, it fails with an error rather than falling back to the default.

To make xAI the default image provider:

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

Note

xAI's own docs also cover quality, mask, user, and an auto aspect ratio. At present OpenClaw forwards only the image controls shared across providers; image_generate does not expose these native-only knobs.

Text-to-speech

Text-to-speech is registered by the bundled xai plugin through the shared tts provider surface.

  • Voices: live catalog from xAI, authenticated; list them 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 the built-in catalog response does not include them
  • Formats: mp3, wav, pcm, mulaw, alaw
  • Language: a BCP-47 code or auto
  • Speed: override using the provider's native speed setting
  • The native Opus voice-note format is not supported

To make xAI the default TTS provider:

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

Note

For buffered synthesis OpenClaw calls xAI's batch /v1/tts endpoint, discovers the catalog through authenticated /v1/tts/voices, and uses native wss://api.x.ai/v1/tts for streaming synthesis. Streaming only works on the native api.x.ai host, so custom baseUrl values are rejected on that path. The existing language, voice, codec, and speed controls apply; sample rate and bit rate come from xAI's defaults. All configured codecs are honored for audio-file synthesis. Voice-note targets fall back to MP3 for both streaming and buffered output, since xAI's raw codecs carry no codec/rate metadata. On the stream, text.delta is sent first, then text.done; the response is audio.delta, audio.done, or error, and an idle timeoutMs applies, refreshed on each audio chunk. This path is distinct from realtime voice sessions. Consult xAI's Streaming TTS API contract.

Speech-to-text

Batch speech-to-text is registered by the bundled xai plugin via OpenClaw's media-understanding transcription surface.

  • Endpoint: xAI REST /v1/stt
  • Input path: multipart audio file upload
  • Model selection: handled inside xAI; the endpoint offers no model selector
  • Applies 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 may come from the shared audio media config or from a per-call transcription request. The shared OpenClaw surface accepts prompt hints, but the xAI REST STT integration forwards only file and language, since those are what map to the current public xAI endpoint.

Transcripts that are valid but empty get skipped, and OpenClaw then tries any configured fallback. Malformed responses and HTTP failures still count as errors.

Streaming speech-to-text

A realtime transcription provider for live voice-call audio is also registered by the bundled xai plugin.

  • Endpoint: xAI WebSocket wss://api.x.ai/v1/stt
  • Default encoding: mulaw
  • Default sample rate: 8000
  • Default endpointing: 800ms
  • Interim transcripts: on by default

Dictation previews keep locked chunks through short pauses. When the connection is replaced, those chunks are committed as an interrupted utterance before new speech is shown; unconfirmed text from the previous connection is dropped.

Voice Call's Twilio media stream emits G.711 mu-law audio frames, and the xAI provider passes them straight through with no transcoding:

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "xai",
            providers: {
              xai: {
                apiKey: "${XAI_API_KEY}",
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}

Provider-owned settings sit under plugins.entries.voice-call.config.streaming.providers.xai. The keys you can use are apiKey, baseUrl, sampleRate, encoding (pcm, mulaw, or alaw), interimResults, endpointingMs, and language.

Note

Voice Call's realtime transcription path is what this streaming provider serves. Discord voice captures short segments, so it goes through the batch tools.media.audio transcription path rather.

Realtime voice (Talk)

Realtime sessions for Grok Voice Agent in Talk mode are registered by the bundled xai plugin, which works 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 (relay paths for iOS, Android, and Control UI)
  • Audio: PCM16 24 kHz or G.711 µ-law 8 kHz
  • Barge-in: the xAI server VAD cuts off the response; OpenClaw drops queued playback and truncates provider history that was never played

Set up 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-..." } },
}

When Voice Call or the shared realtime selectors reuse the same provider map, provider-owned config is also resolved from plugins.entries.voice-call.config.realtime.providers.xai. The supported keys are apiKey, baseUrl, model, voice, vadThreshold, silenceDurationMs, prefixPaddingMs, reasoningEffort, and sessionResumption. Only high or none is accepted by reasoningEffort, which matches the xAI Voice Agent API.

Responses are always created by xAI's server VAD, and that same VAD handles audio interruption. Use consultRouting: "provider-direct"; the xAI Voice Agent protocol does not support forced transcript routing or turning off input-audio interruption.

Note

Realtime voice can be authenticated with xAI OAuth or XAI_API_KEY. Browser-owned WebRTC is not yet covered by this provider surface; on native nodes use gateway-relay Talk, or the Control UI relay path.

Note

sessionResumption is set to false by default. With true, OpenClaw requests that xAI keep enough session state to resume the same conversation after a reconnect, then reconnects using the conversation id that comes back. If provider-side replay/retention is not acceptable, leave it disabled: interrupted sockets will then stop rather than quietly beginning a new conversation.

x_search configuration

x_search is exposed by the bundled xAI plugin as an OpenClaw tool that searches X (formerly Twitter) content through Grok.

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

KeyTypeDefaultDescription
enabledbooleanAutomatic for xAI modelsDisable, or opt in for a known non-xAI provider
modelstringgrok-4.7Model used for x_search requests
baseUrlstring-xAI Responses base URL override
inlineCitationsboolean-Include inline citations in results
maxTurnsnumber-Maximum conversation turns
timeoutSecondsnumber30Request timeout in seconds
cacheTtlMinutesnumber15Cache time-to-live in minutes
{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true,
            model: "grok-4.3",
            baseUrl: "https://api.x.ai/v1",
            inlineCitations: true,
          },
        },
      },
    },
  },
}

Code execution configuration

code_execution is exposed by the bundled xAI plugin as an OpenClaw tool for running code remotely inside xAI's sandbox environment.

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

KeyTypeDefaultDescription
enabledbooleanAutomatic for xAI modelsTurn off, or explicitly enable for a known non-xAI provider
modelstringgrok-4.7Model that handles code execution requests
maxTurnsnumber-Upper bound on conversation turns
timeoutSecondsnumber30How many seconds a request may take

Note

Execution happens in xAI's remote sandbox, not through a local exec.

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

Context compaction

By default, native api.x.ai Responses routes call xAI's server-side /responses/compact endpoint, both for manual /compact and for preflight compaction triggered by thresholds. The OpenClaw transcript itself is left untouched by the session, which instead retains xAI's opaque checkpoint for the following request. Token counts before and after are reported in completion notices, as supplied by the provider.

To turn the endpoint off for a single model:

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

Providers compatible with Responses may enable it through params.responsesCompactEndpoint: true; routes that are not Responses-based disregard that setting. This endpoint is likewise on by default in the public OpenAI Responses API, where it serves budget compaction and /compact. Control of its inline context_management compaction is handled separately via responsesServerCompaction.

When the endpoint fails, OpenClaw falls back to summarizing on the client side. Recovery from a provider-confirmed overflow never invokes the endpoint, since xAI demands that input fit the model context window before compaction happens. Predicted pressure, by contrast, may attempt the endpoint before the next turn is submitted.

Known limits

  • Authentication for xAI accepts an API key, an environment variable, a plugin config fallback, or OAuth tied to an eligible xAI account. Device-code verification is used for OAuth, with no localhost callback. Which accounts are allowed to receive OAuth API tokens is decided by xAI, and the consent page might display Grok Build even though the Grok Build app is not needed by OpenClaw.
  • The xAI multi-agent model family is not exposed by OpenClaw at present. xAI delivers these models via the Responses API, yet they reject the client-side and custom tools that OpenClaw's shared agent loop relies on. Consult the xAI multi-agent limitations.
  • For xAI Realtime voice, only the gateway-relay Talk transport is available right now. Provider WebSocket sessions owned by the browser are not yet connected in the Control UI.
  • xAI image quality, image mask, and additional native-only aspect ratios remain unexposed until the shared image_generate tool gains matching cross-provider controls.

Advanced notes

  • On the shared runner path, xAI-specific compatibility fixes for tool schemas and tool calls are applied by OpenClaw automatically.
  • Tool images stay bound to their tool results in native https://api.x.ai/v1 Responses requests. On compatibility routes (Grok OAuth among them), each consecutive group of tool results is followed by a labeled user image message for image-capable models. Results from parallel calls remain grouped, and the historical image position is kept across later turns so prompt caching still works. A new history prefix and result numbering are established by compaction.
  • Native xAI requests default to tool_stream: true. To disable it, set agents.defaults.models["xai/<model>"].params.tool_stream to false.
  • Before native xAI requests are sent, the bundled xAI wrapper removes schema bounds for contains-count that are unsupported, along with unsupported reasoning effort payload keys. Low, medium, high, and xhigh effort are supported by Grok 4.7 and Grok 4.6 (default high). Grok 4.5 accepts low, medium, and high effort (default high). None, low, medium, and high effort are accepted by Grok 4.3 (default low). No configurable effort control is exposed on other reasoning-capable xAI models, yet they still request include: ["reasoning.encrypted_content"] so that encrypted reasoning from earlier turns can be replayed on follow-ups. With those models, the off setting in OpenClaw drops the effort override; the model's native reasoning is not switched off by it.
  • OpenClaw tools are provided for web_search, x_search, and code_execution. Rather than attaching every native tool to each chat turn, OpenClaw adds just the one xAI built-in that a given tool requires to that tool's request.
  • plugins.entries.xai.config.webSearch.baseUrl is read by Grok web_search. x_search reads plugins.entries.xai.config.xSearch.baseUrl, then falls back to the Grok web-search base URL.
  • Ownership of x_search and code_execution sits with the bundled xAI plugin; they are not hardcoded into the core model runtime.
  • code_execution means remote xAI sandbox execution, not a local exec.

Live testing

Unit tests cover the xAI media paths, and opt-in live suites do as well. Before running live checks, export XAI_API_KEY into 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.7,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

Normal TTS, telephony-friendly PCM TTS, audio transcription through xAI batch STT, streaming of the same PCM through xAI realtime STT, text-to-image generation, and reference image editing are all exercised by the provider-specific live file. Through OpenClaw's runtime selection, fallback, normalization, and media attachment path, the shared image live file checks the same xAI provider. One generated first-frame image at 1080P is submitted by the opt-in Video 1.5 case, which then verifies that the finished video downloads.

4,640 words · updated Oct 26, 2026