xAI
OpenClaw ships a bundled xai provider plugin for Grok models.
Getting started
- Create an API key
Create an API key in the xAI console.
- Set your API key
Set
XAI_API_KEY, or run:openclaw onboard --auth-choice xai-api-key - Pick a model
{ agents: { defaults: { model: { primary: "xai/grok-4" } } }, }
OpenClaw uses the xAI Responses API as the bundled xAI transport. The same
XAI_API_KEY can also power Grok-backed web_search, first-class x_search,
and remote code_execution.
If you store an xAI key under plugins.entries.xai.config.webSearch.apiKey,
the bundled xAI model provider reuses that key as a fallback too.
code_execution tuning lives under plugins.entries.xai.config.codeExecution.
Bundled model catalog
OpenClaw includes these xAI model families out of the box:
| Family | Model ids |
|---|---|
| Grok 3 | grok-3, grok-3-fast, grok-3-mini, grok-3-mini-fast |
| Grok 4 | grok-4, grok-4-0709 |
| Grok 4 Fast | grok-4-fast, grok-4-fast-non-reasoning |
| Grok 4.1 Fast | grok-4-1-fast, grok-4-1-fast-non-reasoning |
| Grok 4.20 Beta | grok-4.20-beta-latest-reasoning, grok-4.20-beta-latest-non-reasoning |
| Grok Code | grok-code-fast-1 |
The plugin also forward-resolves newer grok-4* and grok-code-fast* ids when
they follow the same API shape.
grok-4-fast, grok-4-1-fast, and the grok-4.20-beta-* variants are the
current image-capable Grok refs in the bundled catalog.
Fast-mode mappings
/fast on or agents.defaults.models["xai/<model>"].params.fastMode: true
rewrites native xAI requests as follows:
| 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 aliases
Legacy aliases still normalize to the canonical bundled ids:
| Legacy alias | Canonical id |
|---|---|
grok-4-fast-reasoning | grok-4-fast |
grok-4-1-fast-reasoning | grok-4-1-fast |
grok-4.20-reasoning | grok-4.20-beta-latest-reasoning |
grok-4.20-non-reasoning | grok-4.20-beta-latest-non-reasoning |
Features
Web search
The bundled grok web-search provider uses XAI_API_KEY too:
openclaw config set tools.web.search.provider grok
Video generation
The bundled xai plugin registers video generation through the shared
video_generate tool.
- Default video model:
xai/grok-imagine-video - Modes: text-to-video, image-to-video, and remote video edit/extend flows
- Supports
aspectRatioandresolution
Local video buffers are not accepted. Use remote http(s) URLs for
video-reference and edit inputs.
To use xAI as the default video provider:
{
agents: {
defaults: {
videoGenerationModel: {
primary: "xai/grok-imagine-video",
},
},
},
}
See Video Generation for shared tool parameters, provider selection, and failover behavior.
x_search configuration
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
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | — | Enable or disable x_search |
model | string | grok-4-1-fast | Model used for x_search requests |
inlineCitations | boolean | — | Include inline citations in results |
maxTurns | number | — | Maximum conversation turns |
timeoutSeconds | number | — | Request timeout in seconds |
cacheTtlMinutes | number | — | Cache time-to-live in minutes |
{
plugins: {
entries: {
xai: {
config: {
xSearch: {
enabled: true,
model: "grok-4-1-fast",
inlineCitations: true,
},
},
},
},
},
}
Code execution configuration
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
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true (if key available) | Enable or disable code execution |
model | string | grok-4-1-fast | Model used for code execution requests |
maxTurns | number | — | Maximum conversation turns |
timeoutSeconds | number | — | Request timeout in seconds |
This is remote xAI sandbox execution, not local exec.
{
plugins: {
entries: {
xai: {
config: {
codeExecution: {
enabled: true,
model: "grok-4-1-fast",
},
},
},
},
},
}
Known limits
- Auth is API-key only today. There is no xAI OAuth or device-code flow in OpenClaw yet.
grok-4.20-multi-agent-experimental-beta-0304is not supported on the normal xAI provider path because it requires a different upstream API surface than the standard OpenClaw xAI transport.
Advanced notes
- OpenClaw applies xAI-specific tool-schema and tool-call compatibility fixes automatically on the shared runner path.
- Native xAI requests default
tool_stream: true. Setagents.defaults.models["xai/<model>"].params.tool_streamtofalseto disable it. - The bundled xAI wrapper strips unsupported strict tool-schema flags and reasoning payload keys before sending native xAI requests.
web_search,x_search, andcode_executionare exposed as OpenClaw tools. OpenClaw enables the specific xAI built-in it needs inside each tool request instead of attaching all native tools to every chat turn.x_searchandcode_executionare owned by the bundled xAI plugin rather than hardcoded into the core model runtime.code_executionis remote xAI sandbox execution, not localexec.