在 OpenClaw 中接入 Grok 系列模型，有 OAuth 和 API Key 两条路径。新安装推荐 openclaw onboard --install-daemon 并选择 xAI OAuth；已有安装用 openclaw models auth login --provider xai --method oauth 只登录 xAI，无需重跑完整 onboarding。SSH/Docker/VPS 环境必须使用设备码 --device-code。登录后用 openclaw models set xai/grok-4.3 设为默认模型。OAuth 不需要 xAI API Key，也不需要 Grok Build 应用。如果浏览器回环地址 127.0.0.1:56121 不可达，设备码是唯一选项。API Key 认证用于控制台密钥和需要密钥的后端配置。

OpenClaw 接入 xAI Grok 模型：OAuth/API Key 配置、Web 搜索与媒体生成

OpenClaw 内置 xai 提供商插件，用于 Grok 系列模型。推荐路径是使用符合条件的 SuperGrok 或 X Premium 订阅进行 Grok OAuth 认证。OpenClaw 保持本地优先：网关、配置、路由和工具运行在你的设备上，Grok 模型请求通过 xAI 认证后发送到 xAI API。

OAuth 不需要 xAI API Key，也不需要 Grok Build 应用。xAI 可能在授权界面仍显示 Grok Build，因为 OpenClaw 使用 xAI 的共享 OAuth 客户端。

选择你的配置路径

根据你当前的 OpenClaw 安装状态选择对应路径：

全新安装 OpenClaw
在设置新本地网关时，使用带守护进程安装的 onboarding，然后在模型/认证步骤中选择 xAI/Grok OAuth：
bash
```
openclaw onboard --install-daemon
```
如果在 VPS 或通过 SSH 安装，在 onboarding 中使用设备码：
bash
```
openclaw onboard --install-daemon --auth-choice xai-device-code
```
已有 OpenClaw 安装
如果 OpenClaw 已配置好，只登录 xAI 即可，不要重新运行完整 onboarding 或重新安装守护进程：
bash
```
openclaw models auth login --provider xai --method oauth
```
当网关运行在 SSH、Docker 或 VPS 上，本地浏览器回环不方便时，使用设备码流程：
bash
```
openclaw models auth login --provider xai --device-code
```
登录后让 Grok 成为默认模型：
bash
```
openclaw models set xai/grok-4.3
```
只有在有意更改网关、守护进程、渠道、工作区或其他设置时才重跑完整 onboarding。
API Key 路径
API Key 设置仍可用于 xAI 控制台密钥，以及需要密钥支持的媒体配置：
bash
```
openclaw models auth login --provider xai --method api-key
export XAI_API_KEY=xai-...
```

选择模型
在配置文件中指定：

json5

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

说明：OpenClaw 使用 xAI Responses API 作为内置传输。使用上述任意方式获得的同一凭据，还可驱动一等 web_search、x_search、远程 code_execution 以及 xAI 图像/视频生成。语音和转录功能当前需要 XAI_API_KEY 或提供商配置。Grok 驱动的 web_search 优先使用 xAI OAuth，回退到 XAI_API_KEY 或插件 web-search 配置。如果在 plugins.entries.xai.config.webSearch.apiKey 中存储了 xAI 密钥，内置 xAI 模型提供商也会将其作为回退密钥。设置 plugins.entries.xai.config.webSearch.baseUrl 可将 Grok web_search 和默认的 x_search 路由到运营商的 xAI Responses 代理。code_execution 调优参数位于 plugins.entries.xai.config.codeExecution。

OAuth 故障排查

如果浏览器 OAuth 无法访问 127.0.0.1:56121，使用 openclaw models auth login --provider xai --device-code。
如果登录成功但 Grok 不是默认模型，运行 openclaw models set xai/grok-4.3。

查看已保存的 xAI 认证配置文件：

bash

openclaw models auth list --provider xai
openclaw models status

xAI 决定哪些账户可以接收 OAuth API 令牌。如果账户不符合条件，尝试 API Key 路径或检查 xAI 侧的订阅。

技巧：通过 SSH、Docker 或 VPS 登录时使用 xai-device-code。OpenClaw 会打印一个 xAI URL 和短码；在任意本地浏览器中完成登录，远程进程会轮询 xAI 获取完成的令牌交换。

内置模型目录

OpenClaw 内置当前 xAI 聊天模型，在模型选择器中按最新优先排序：

系列	模型 ID
Grok Build 0.1	`grok-build-0.1`
Grok 4.3	`grok-4.3`
Grok 4.20 Beta	`grok-4.20-beta-latest-reasoning`, `grok-4.20-beta-latest-non-reasoning`

插件还会前向解析旧的 Grok 3、Grok 4、Grok 4 Fast、Grok 4.1 Fast 和 Grok Code 等标识符，以兼容现有配置。官方 Grok Code Fast 别名规范化为 grok-build-0.1；OpenClaw 不再在可选目录中显示其他已退役的上游标识符。

技巧：通用聊天使用 grok-4.3，构建/编码类工作负载使用 grok-build-0.1，除非你明确需要 Grok 4.20 Beta 别名。

OpenClaw 功能覆盖

内置插件将 xAI 当前的公开 API 表面映射到 OpenClaw 的共享提供商和工具契约。不适合共享契约的能力（如流式 TTS 和实时语音）不暴露——见下表：

xAI 能力	OpenClaw 表面	状态
聊天 / Responses	`xai/<model>` 模型提供商	支持
服务端网页搜索	`web_search` 提供商 `grok`	支持
服务端 X 搜索	`x_search` 工具	支持
服务端代码执行	`code_execution` 工具	支持
图像生成	`image_generate`	支持
视频生成	`video_generate`	支持
批量文本转语音	`messages.tts.provider: "xai"` / `tts`	支持
流式 TTS	-	不暴露（OpenClaw TTS 契约返回完整音频缓冲区）
批量语音转文本	`tools.media.audio` / 媒体理解	支持
流式语音转文本	Voice Call `streaming.provider: "xai"`	支持
实时语音	-	尚未暴露（不同的会话/WebSocket 契约）
文件 / 批次	仅通用模型 API 兼容	不是一等 OpenClaw 工具

说明：OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、语音和批量转录，使用 xAI 的流式 STT WebSocket 进行实时语音呼叫转录，使用 Responses API 进行模型、搜索和代码执行工具。需要不同 OpenClaw 契约的功能（如实时语音会话）作为上游能力在此记录，而不是隐藏的插件行为。

Fast 模式映射

启用 /fast on 或 agents.defaults.models["xai/<model>"].params.fastMode: true 后，原生 xAI 请求被重写如下：

源模型	Fast 模式目标
`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-code-fast-1`	`grok-build-0.1`
`grok-code-fast`	`grok-build-0.1`
`grok-code-fast-1-0825`	`grok-build-0.1`
`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`

功能详情

Web 搜索

内置的 grok web 搜索提供商优先使用 xAI OAuth，然后回退到 XAI_API_KEY 或插件 web 搜索密钥：

bash

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

视频生成

内置的 xai 插件通过共享的 video_generate 工具注册视频生成。

默认视频模型：xai/grok-imagine-video
模式：文本转视频、图像转视频、参考图像生成、远程视频编辑、远程视频扩展
宽高比：1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
分辨率：480P, 720P
时长：生成/图像转视频 1–15 秒，使用 reference_image 角色时 1–10 秒，扩展时 2–10 秒
参考图像生成：将 imageRoles 设置为 reference_image，xAI 最多接受 7 张这样的图像
默认操作超时：600 秒（除非设置了 video_generate.timeoutMs 或 agents.defaults.videoGenerationModel.timeoutMs）

警告

不接受本地视频缓冲区。视频编辑/扩展输入请使用远程 http(s) URL。图像转视频接受本地图像缓冲区，因为 OpenClaw 可以将其编码为 data URL 发送给 xAI。

使用 xAI 作为默认视频提供商：

json5

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

共享工具参数、提供商选择和故障转移行为参见视频生成。

图像生成

内置的 xai 插件通过共享的 image_generate 工具注册图像生成。

默认图像模型：xai/grok-imagine-image
额外模型：xai/grok-imagine-image-quality
模式：文本转图像、参考图像编辑
参考输入：一个 image 或最多五个 images
宽高比：1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2
分辨率：1K, 2K
数量：最多 4 张图像
默认操作超时：600 秒（除非设置了 image_generate.timeoutMs 或 agents.defaults.imageGenerationModel.timeoutMs）

OpenClaw 向 xAI 请求 b64_json 图像响应，以便生成的媒体可以通过常规渠道附件路径存储和传递。本地参考图像转换为 data URL；远程 http(s) 引用直接传递。

使用 xAI 作为默认图像提供商：

json5

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

xAI 还记录了 quality、mask、user 以及额外的原生宽高比（如 1:2、2:1、9:20、20:9）。OpenClaw 当前只转发共享的跨提供商图像控制参数；不支持的原生独有参数不会通过 image_generate 暴露。

文本转语音

内置的 xai 插件通过共享的 tts 提供商表面注册文本转语音。

声音：eve, ara, rex, sal, leo, una
默认声音：eve
格式：mp3, wav, pcm, mulaw, alaw
语言：BCP-47 代码或 auto
速度：提供商原生速度覆盖
不支持原生 Opus 语音便签格式

使用 xAI 作为默认 TTS 提供商：

json5

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

OpenClaw 使用 xAI 的批量 /v1/tts 端点。xAI 还提供基于 WebSocket 的流式 TTS，但 OpenClaw 语音提供商契约当前期望在回复传递前获得完整音频缓冲区。

语音转文本（批量）

内置的 xai 插件通过 OpenClaw 的媒体理解转录表面注册批量语音转文本。

默认模型：grok-stt
端点：xAI REST /v1/stt
输入路径：multipart 音频文件上传
OpenClaw 中凡是使用 tools.media.audio 的入站音频转录（包括 Discord 语音频道片段和频道音频附件）都支持

强制 xAI 处理入站音频转录：

json5

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

语言可以通过共享音频媒体配置或每次调用转录请求提供。OpenClaw 共享表面接受提示 hint，但 xAI REST STT 集成只传递文件、模型和语言，因为只有这些能干净地映射到当前公开的 xAI 端点。

流式语音转文本

内置的 xai 插件还注册了一个实时转录提供商，用于语音呼叫的实时音频。

端点：xAI WebSocket wss://api.x.ai/v1/stt
默认编码：mulaw
默认采样率：8000
默认断句时间：800ms
中期转录：默认启用

Voice Call 的 Twilio 媒体流发送 G.711 µ-law 音频帧，因此 xAI 提供商可以直接转发这些帧而无需转码：

json5

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "xai",
            providers: {
              xai: {
                apiKey: "${XAI_API_KEY}",
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}

提供商自有配置位于 plugins.entries.voice-call.config.streaming.providers.xai。支持的键有 apiKey、baseUrl、sampleRate、encoding（pcm、mulaw 或 alaw）、interimResults、endpointingMs 和 language。

此流式提供商用于 Voice Call 的实时转录路径。Discord 语音当前录制短片段并使用批量 tools.media.audio 转录路径。

x_search 配置

内置的 xAI 插件将 x_search 作为 OpenClaw 工具暴露，用于通过 Grok 搜索 X（原 Twitter）内容。

配置路径：plugins.entries.xai.config.xSearch

键	类型	默认值	描述
`enabled`	boolean	-	启用或禁用 x_search
`model`	string	`grok-4-1-fast`	用于 x_search 请求的模型
`baseUrl`	string	-	xAI Responses 基础 URL 覆盖
`inlineCitations`	boolean	-	在结果中包含内联引用
`maxTurns`	number	-	最大对话轮数
`timeoutSeconds`	number	-	请求超时秒数
`cacheTtlMinutes`	number	-	缓存过期分钟数

json5

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

代码执行配置

内置的 xAI 插件将 code_execution 作为 OpenClaw 工具暴露，用于在 xAI 沙箱环境中远程执行代码。

配置路径：plugins.entries.xai.config.codeExecution

键	类型	默认值	描述
`enabled`	boolean	`true`（如有密钥可用）	启用或禁用代码执行
`model`	string	`grok-4-1-fast`	用于代码执行请求的模型
`maxTurns`	number	-	最大对话轮数
`timeoutSeconds`	number	-	请求超时秒数

这是远程 xAI 沙箱执行，而非本地 exec 工具。

json5

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

已知限制

xAI 认证可以使用 API Key、环境变量、插件配置回退、浏览器 OAuth 或设备码 OAuth（需要符合条件的 xAI 账户）。浏览器 OAuth 使用 127.0.0.1:56121 上的本地回环；对于远程主机，除非你打算在打开登录 URL 前转发该端口，否则使用 xai-device-code。xAI 决定哪些账户可以接收 OAuth API 令牌，授权页面可能显示 Grok Build，即使 OpenClaw 不需要 Grok Build 应用。
grok-4.20-multi-agent-experimental-beta-0304 在普通 xAI 提供商路径上不受支持，因为它需要与标准 OpenClaw xAI 传输不同的上游 API 表面。
xAI Realtime 语音尚未注册为 OpenClaw 提供商。它需要不同于批量 STT 或流式转录的双向语音会话契约。
xAI 图像的 quality、mask 和额外的原生宽高比在共享 image_generate 工具有了对应的跨提供商控制之前不暴露。

高级说明

OpenClaw 自动在共享运行路径上应用 xAI 特定的工具 schema 和工具调用兼容性修复。
原生 xAI 请求默认启用 tool_stream: true。设置 agents.defaults.models["xai/<model>"].params.tool_stream 为 false 可禁用。
内置的 xAI 包装器会在发送原生 xAI 请求前剥离不支持的 strict 工具 schema 标志和推理 payload 键。
web_search、x_search 和 code_execution 作为 OpenClaw 工具暴露。OpenClaw 在每个工具请求内部启用所需的特定 xAI 内置工具，而不是将全部原生工具附加到每轮对话。
Grok web_search 读取 plugins.entries.xai.config.webSearch.baseUrl。x_search 读取 plugins.entries.xai.config.xSearch.baseUrl，然后回退到 Grok web-search 基础 URL。
x_search 和 code_execution 由内置 xAI 插件拥有，而非硬编码到核心模型运行时。
code_execution 是远程 xAI 沙箱执行，与本地 exec 无关。

实时测试

xAI 媒体路径通过单元测试和可选实时套件覆盖。在运行实时探测前，请导出 XAI_API_KEY 到进程环境：

bash

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

提供商特定的实时文件会合成普通 TTS、电话友好 PCM TTS、通过 xAI 批量 STT 转录音频、通过 xAI 实时 STT 流式传输相同 PCM、生成文本转图像输出以及编辑参考图像。共享图像实时文件通过 OpenClaw 的运行时选择、回退、规范化和媒体附件路径验证同一个 xAI 提供商。

常见问题

OpenClaw xAI 设备码怎么用？

在 SSH/Docker/VPS 环境运行 OpenClaw 时，使用 openclaw models auth login --provider xai --device-code。终端会打印一个 xAI URL 和短码，在本地浏览器中打开 URL 并输入短码完成授权，远程进程自动轮询直到令牌交换完成。

OAuth 登录后 Grok 还不是默认模型怎么处理？

登录成功后运行 openclaw models set xai/grok-4.3 单独设置默认模型。如果仍不生效，用 openclaw models auth list --provider xai 和 openclaw models status 检查认证状态和当前模型配置。

xAI 视频生成提示“不支持本地文件”怎么办？

视频编辑/扩展输入必须使用远程 https:// URL，不接受本地文件。先将本地视频上传到可公开访问的云存储（如 AWS S3、Cloudflare R2、阿里云 OSS），再用该 URL 作为 video_generate 的参考输入。图像转视频支持本地图像，因为 OpenClaw 可以将其编码为 data URL。

OpenClaw 接入 xAI Grok 模型：OAuth/API Key 配置、Web 搜索与媒体生成 ​

选择你的配置路径 ​

OAuth 故障排查 ​

内置模型目录 ​

OpenClaw 功能覆盖 ​

Fast 模式映射 ​

兼容旧别名 ​

功能详情 ​

Web 搜索 ​

视频生成 ​

图像生成 ​

文本转语音 ​

语音转文本（批量） ​

流式语音转文本 ​

x_search 配置 ​

代码执行配置 ​

已知限制 ​

高级说明 ​

实时测试 ​

相关文档 ​

常见问题 ​

OpenClaw xAI 设备码怎么用？ ​

OAuth 登录后 Grok 还不是默认模型怎么处理？ ​

xAI 视频生成提示“不支持本地文件”怎么办？ ​

OpenClaw 接入 xAI Grok 模型：OAuth/API Key 配置、Web 搜索与媒体生成

选择你的配置路径

OAuth 故障排查

内置模型目录

OpenClaw 功能覆盖

Fast 模式映射

兼容旧别名

功能详情

Web 搜索

视频生成

图像生成

文本转语音

语音转文本（批量）

流式语音转文本

x_search 配置

代码执行配置

已知限制

高级说明

实时测试

相关文档

常见问题

OpenClaw xAI 设备码怎么用？

OAuth 登录后 Grok 还不是默认模型怎么处理？

xAI 视频生成提示“不支持本地文件”怎么办？