Skip to main content

​
xAI

Velaclaw ships a bundled xai provider plugin for Grok models.

​
Getting started

1

Create an API key

Create an API key in the xAI console.
2

Set your API key

Set XAI_API_KEY, or run:
3

Pick a model

Velaclaw 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

Velaclaw includes these xAI model families out of the box: 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:

​
Legacy compatibility aliases

Legacy aliases still normalize to the canonical bundled ids:

​
Features

The bundled grok web-search provider uses XAI_API_KEY too:
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
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:
See Video Generation for shared tool parameters, provider selection, and failover behavior.
The bundled xAI plugin exposes x_search as an Velaclaw tool for searching X (formerly Twitter) content via Grok.Config path: plugins.entries.xai.config.xSearch
The bundled xAI plugin exposes code_execution as an Velaclaw tool for remote code execution in xAI’s sandbox environment.Config path: plugins.entries.xai.config.codeExecution
This is remote xAI sandbox execution, not local exec.
  • Auth is API-key only today. There is no xAI OAuth or device-code flow in Velaclaw 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 Velaclaw xAI transport.
  • Velaclaw 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/<model>"].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 Velaclaw tools. Velaclaw 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.

Model selection

Choosing providers, model refs, and failover behavior.

Video generation

Shared video tool parameters and provider selection.

All providers

The broader provider overview.

Troubleshooting

Common issues and fixes.