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 oauthor--method api-key, also drivesweb_search(provider idgrok),x_search,code_execution, speech/transcription, and xAI image/video generation. Should you store an xAI key underplugins.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,
offis not offered. If the picker shows effort levels for a model but--thinkingrejects them, the login predates this behavior: rerunopenclaw models auth login --provider xai --method oauthto 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-oauthwhen 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.
| Family | Model ids |
|---|---|
| Grok 4.7 | grok-4.7 (alias: grok-4.7-latest) |
| Grok 4.6 | grok-4.6 |
| Grok 4.5 | grok-4.5 (aliases: grok-4.5-latest, grok-build-latest) |
| Grok Build 0.1 | grok-build-0.1 |
| Grok 4.3 | grok-4.3 (aliases: grok-4.3-latest, grok-latest) |
| Grok 4.20 | grok-4.20-0309-reasoning, grok-4.20-0309-non-reasoning |
Tip
Both OAuth and API-key setup treat
xai/grok-4.7as 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 capability | OpenClaw surface | Status |
|---|---|---|
| Chat / Responses | xai/<model> model provider | Yes |
| Context compaction | /compact and threshold compaction | Yes via /v1/responses/compact |
| 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 | tts.provider: "xai" / tts | Yes |
| Streaming TTS | textToSpeechStream | Yes via wss://api.x.ai/v1/tts (not realtime voice) |
| Batch speech-to-text | tools.media.audio media understanding | Yes |
| Streaming speech-to-text | Voice Call streaming.provider: "xai" | Yes |
| Realtime voice | Talk talk.realtime.provider: "xai" | Yes; gateway-relay for native Talk nodes |
| Files / batches | Generic model API compatibility only | Not 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 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 and moving aliases
Legacy aliases are normalized as follows:
| Legacy alias | Normalized id |
|---|---|
grok-code-fast-1, grok-code-fast, grok-code-fast-1-0825 | grok-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 ids | Current behavior |
|---|---|
grok-4-1-fast-reasoning, grok-4-fast-reasoning, grok-4-0709 | Grok 4.3 with low reasoning |
grok-4-1-fast-non-reasoning, grok-4-fast-non-reasoning, grok-3 | Grok 4.3 with reasoning disabled |
grok-code-fast-1 | Grok Build 0.1 |
grok-imagine-image-pro | Grok 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_searchandcode_executionexecute 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'senabledsetting is left out, OpenClaw offers that tool only while an xAI model is active. For a known non-xAI model provider, an explicit per-toolenabled: trueis required; if the provider is missing or cannot be resolved, the request is blocked. xAI authentication is required in all cases, andenabled: falseturns the tool off for every provider.
Web search
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/720Pfor classic; Video 1.5 additionally accepts1080P; every generation mode defaults to480P - Duration: 1-15 seconds for generation and image-to-video, 1-10 seconds with classic
reference_imageroles, 2-10 seconds for classic extension - Reference-image generation: for each image you supply, set
imageRolestoreference_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.timeoutMsoragents.defaults.mediaModels.video.timeoutMsis 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
imageor as many as threeimages - 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.timeoutMsoragents.defaults.mediaModels.image.timeoutMsis 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 anautoaspect ratio. At present OpenClaw forwards only the image controls shared across providers;image_generatedoes 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/ttsendpoint, discovers the catalog through authenticated/v1/tts/voices, and uses nativewss://api.x.ai/v1/ttsfor streaming synthesis. Streaming only works on the nativeapi.x.aihost, so custombaseUrlvalues 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.deltais sent first, thentext.done; the response isaudio.delta,audio.done, orerror, and an idletimeoutMsapplies, 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.audiotranscription 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
sessionResumptionis set tofalseby default. Withtrue, 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
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | Automatic for xAI models | Disable, or opt in for a known non-xAI provider |
model | string | grok-4.7 | 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 |
{
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
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | Automatic for xAI models | Turn off, or explicitly enable for a known non-xAI provider |
model | string | grok-4.7 | Model that handles code execution requests |
maxTurns | number | - | Upper bound on conversation turns |
timeoutSeconds | number | 30 | How 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, imagemask, and additional native-only aspect ratios remain unexposed until the sharedimage_generatetool 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/v1Responses 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, setagents.defaults.models["xai/<model>"].params.tool_streamtofalse. - 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, theoffsetting 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, andcode_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.baseUrlis read by Grokweb_search.x_searchreadsplugins.entries.xai.config.xSearch.baseUrl, then falls back to the Grok web-search base URL.- Ownership of
x_searchandcode_executionsits with the bundled xAI plugin; they are not hardcoded into the core model runtime. code_executionmeans remote xAI sandbox execution, not a localexec.
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.
Related
-
Model selection, Picking providers, model refs, and how failover works.
-
Video generation, Parameters shared by the video tool, plus provider choice.
-
All providers, A wider look at the providers.
-
Troubleshooting, Typical problems and their fixes.