openclaw/docs/providers/xai.md

summary, read_when, title

summary	read_when	title
Use xAI Grok models in OpenClaw	You want to use Grok models in OpenClaw You are configuring xAI auth or model ids	xAI

xAI

OpenClaw ships a bundled xai provider plugin for Grok models.

Getting started

Create an API key in the [xAI console](https://console.x.ai/). Set `XAI_API_KEY`, or run:

```bash
openclaw onboard --auth-choice xai-api-key
```

```json5 { 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

The bundled `grok` web-search provider uses `XAI_API_KEY` too:

```bash
openclaw config set tools.web.search.provider grok
```

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 `aspectRatio` and `resolution`

<Warning>
Local video buffers are not accepted. Use remote `http(s)` URLs for
video-reference and edit inputs.
</Warning>

To use xAI as the default video provider:

```json5
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "xai/grok-imagine-video",
      },
    },
  },
}
```

<Note>
See [Video Generation](/tools/video-generation) for shared tool parameters,
provider selection, and failover behavior.
</Note>

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        |

```json5
{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true,
            model: "grok-4-1-fast",
            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`

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

<Note>
This is remote xAI sandbox execution, not local [`exec`](/tools/exec).
</Note>

```json5
{
  plugins: {
    entries: {
      xai: {
        config: {
          codeExecution: {
            enabled: true,
            model: "grok-4-1-fast",
          },
        },
      },
    },
  },
}
```

- 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-0304` is not supported on the normal xAI provider path because it requires a different upstream API surface than the standard OpenClaw xAI transport. - OpenClaw applies xAI-specific tool-schema and tool-call compatibility fixes automatically on the shared runner path. - Native xAI requests default `tool_stream: true`. Set `agents.defaults.models["xai/"].params.tool_stream` to `false` to 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`, and `code_execution` are 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_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`](/tools/exec).

Related

Choosing providers, model refs, and failover behavior. Shared video tool parameters and provider selection. The broader provider overview. Common issues and fixes.