本页介绍如何在 OpenClaw 中配置 xAI Provider 以使用 Grok 系列模型。通过 XAI_API_KEY 认证，支持 Grok-4、Grok-3、grok-code-fast-1 等全系模型，以及 Grok 网页搜索（web_search）、X 搜索（x_search）、远程代码执行（code_execution）和视频生成（grok-imagine-video）能力。当前仅支持 API Key 认证，暂无 OAuth 流程。

xAI

OpenClaw 内置 xai Provider 插件，用于接入 Grok 系列模型。

快速上手

在 xAI 控制台创建 API Key
设置 XAI_API_KEY，或运行：

bash

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

设置默认模型：

json5

{
  agents: { defaults: { model: { primary: "xai/grok-4" } } },
}

xAI 现在使用 xAI Responses API 作为内置传输。同一个 XAI_API_KEY 还可驱动 Grok 网页搜索、X 搜索和远程代码执行。

内置模型目录

OpenClaw 当前内置以下 xAI 模型系列：

系列	模型 ID
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-non-reasoning`
Grok 4.1	`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-fast-1`

插件还会前向解析新的 grok-4* 和 grok-code-fast* ID（形状相同时）。

Fast Mode 自动切换

/fast on 或 params.fastMode: true 自动将以下模型切换到快速版本：

grok-3 → grok-3-fast
grok-3-mini → grok-3-mini-fast
grok-4 → grok-4-fast
grok-4-0709 → grok-4-fast

兼容别名

旧版模型 ID 自动规范化到当前版本：

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

网页搜索

Grok 网页搜索也使用 XAI_API_KEY：

bash

openclaw config set tools.web.search.provider grok

此外，OpenClaw 还通过 xAI 插件暴露 x_search（X 平台搜索）和 code_execution（远程 xAI 沙箱执行）工具。

code_execution 是 xAI 远程沙箱执行，与本地 exec 工具无关。

视频生成

xAI 通过共享 video_generate 工具注册视频生成：

默认视频模型：xai/grok-imagine-video
支持文本转视频、图像转视频和远程视频编辑/延伸流程
支持 aspectRatio 和 resolution
当前限制：不接受本地视频文件——视频参考/编辑输入必须使用远程 https:// URL

设置 xAI 为默认视频提供商：

json5

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

配置注意事项

tool_stream: true 是原生 xAI 请求的默认值。设置 params.tool_stream: false 可关闭
xAI 插件自动剥离不支持的 strict 工具 schema 标志和推理 payload 键
web_search、x_search、code_execution 作为 OpenClaw 工具暴露，OpenClaw 只在每个工具请求内部启用对应的 xAI 内置工具，不会在每轮对话中附加所有原生工具
如果在 plugins.entries.xai.config.webSearch.apiKey 中存储了 xAI Key，内置 xAI 模型提供商也会将其作为降级 Key 使用
code_execution 调优参数位于 plugins.entries.xai.config.codeExecution

已知限制

当前仅支持 API Key 认证，尚无 xAI OAuth/设备码流程
grok-4.20-multi-agent-experimental-beta-0304 不在普通 xAI Provider 路径中——它需要与标准 OpenClaw xAI 传输不同的上游 API 接口

常见问题

Q: Grok-4 和 Grok-4-fast 有什么区别？

A: Grok-4-fast 是优化吞吐量的快速推理版本，延迟更低但推理深度可能减少。用 /fast on 或 params.fastMode: true 可让 OpenClaw 在 Grok-4 和 Grok-4-fast 之间自动切换，无需手动修改模型 ID。

Q: x_search 和普通 web_search 有什么区别？

A: x_search 是 X（原 Twitter）平台的搜索，专门搜索 X 上的帖子和讨论；web_search 基于 Grok 的通用网页搜索。两者都由 xAI 插件提供，都使用同一个 XAI_API_KEY。

Q: 视频参考必须用远程 URL，本地文件怎么处理？

A: 需要先将本地文件上传到可公开访问的云存储（如 OSS、S3、Cloudflare R2），获取 https:// URL 后再传入 video_generate 工具的参考参数。OpenClaw 会在检测到本地路径时直接返回前置错误，不会发送请求到 xAI 端点。

xAI ​

快速上手 ​

内置模型目录 ​

Fast Mode 自动切换 ​

兼容别名 ​

网页搜索 ​

视频生成 ​

配置注意事项 ​

已知限制 ​

常见问题 ​

xAI