xAI

```bash
openclaw onboard --install-daemon
```

On a VPS or over SSH, select xAI OAuth directly; it uses device-code
verification and does not need a localhost callback:

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

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

Apply Grok as the default model separately:

```bash
openclaw models set xai/grok-4.3
```

Rerun full onboarding only if you intentionally want to change Gateway,
daemon, channel, workspace, or other setup choices.

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

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

- Default video model: `xai/grok-imagine-video`
- Modes: text-to-video, image-to-video, reference-image generation, remote
  video edit, and remote video extension
- Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`
- Resolutions: `480P`, `720P`
- Duration: 1-15 seconds for generation/image-to-video, 1-10 seconds when
  using `reference_image` roles, 2-10 seconds for extension
- Reference-image generation: set `imageRoles` to `reference_image` for
  every supplied image; xAI accepts up to 7 such images
- Default operation timeout: 600 seconds unless `video_generate.timeoutMs`
  or `agents.defaults.videoGenerationModel.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.
</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>

- 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 five `images`
- Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
- Resolutions: `1K`, `2K`
- Count: up to 4 images
- Default operation timeout: 600 seconds unless `image_generate.timeoutMs`
  or `agents.defaults.imageGenerationModel.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:

```json5
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "xai/grok-imagine-image",
      },
    },
  },
}
```

<Note>
xAI also documents `quality`, `mask`, `user`, and additional native ratios
such as `1:2`, `2:1`, `9:20`, and `20:9`. OpenClaw forwards only the shared
cross-provider image controls today; these native-only knobs are not
exposed through `image_generate`.
</Note>

- Voices: `eve`, `ara`, `rex`, `sal`, `leo`, `una`
- Default voice: `eve`
- Formats: `mp3`, `wav`, `pcm`, `mulaw`, `alaw`
- Language: BCP-47 code or `auto`
- Speed: provider-native speed override
- Native Opus voice-note format is not supported

To use xAI as the default TTS provider:

```json5
{
  messages: {
    tts: {
      provider: "xai",
      providers: {
        xai: {
          voiceId: "eve",
        },
      },
    },
  },
}
```

<Note>
OpenClaw uses xAI's batch `/v1/tts` endpoint. xAI also offers streaming
TTS over WebSocket, but the OpenClaw speech provider contract currently
expects a complete audio buffer before reply delivery.
</Note>

- Default model: `grok-stt`
- Endpoint: xAI REST `/v1/stt`
- Input path: multipart audio file upload
- 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:

```json5
{
  tools: {
    media: {
      audio: {
        models: [
          {
            type: "provider",
            provider: "xai",
            model: "grok-stt",
          },
        ],
      },
    },
  },
}
```

Language can be supplied through the shared audio media config or per-call
transcription request. Prompt hints are accepted by the shared OpenClaw
surface, but the xAI REST STT integration forwards only file, model, and
language because those map cleanly to the current public xAI
endpoint.

- 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 sends G.711 mu-law audio frames, so the
xAI provider forwards those frames directly without transcoding:

```json5
{
  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 is for Voice Call's realtime transcription path.
Discord voice records short segments and uses the batch
`tools.media.audio` transcription path instead.
</Note>

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

| Key               | Type    | Default                       | Description                          |
| ----------------- | ------- | ------------------------------ | ------------------------------------- |
| `enabled`         | boolean | `true` (if key available)     | Enable or disable x_search           |
| `model`           | string  | `grok-4-1-fast-non-reasoning` | 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         |

```json5
{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true,
            model: "grok-4-1-fast-non-reasoning",
            baseUrl: "https://api.x.ai/v1",
            inlineCitations: true,
          },
        },
      },
    },
  },
}
```

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

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_TEST_QUIET=1 OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS=xai pnpm test:live -- test/image-generation.runtime.live.test.ts