xAI

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

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

- 默认模型：`xai/grok-imagine-video`
- 附加模型：`xai/grok-imagine-video-1.5`
- 经典模式：文本转视频、图像转视频、参考图像生成、
  远程视频编辑和远程视频扩展
- Video 1.5 模式：仅图像转视频，且恰好包含一张首帧图像
- 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`；
  经典和 Video 1.5 图像转视频在省略时继承源图像比例
- 分辨率：经典 `480P`/`720P`；Video 1.5 还支持 `1080P`；所有
  生成模式默认使用 `480P`
- 时长：生成/图像转视频为 1-15 秒，使用经典 `reference_image` 角色时为 1-10 秒，经典扩展为 2-10 秒
- 参考图像生成：为每个提供的图像将 `imageRoles` 设置为 `reference_image`；xAI 最多接受 7 张此类图像
- 视频编辑/扩展继承输入视频的宽高比和分辨率；
  这些操作不接受几何覆盖
- 默认操作超时：600 秒，除非设置了 `video_generate.timeoutMs`
  或 `agents.defaults.mediaModels.video.timeoutMs`

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

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

OpenClaw 会要求 xAI 返回 `b64_json` 图像响应，以便生成的媒体可以通过正常的渠道附件路径存储和传递。本地
参考图像会被转换为 data URL；远程 `http(s)` 引用会原样传递。

要将 xAI 用作默认图像提供商：

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

{
  tools: {
    media: {
      models: [
        {
          type: "provider",
          provider: "xai",
          capabilities: ["audio"],
        },
      ],
      audio: {
        enabled: true,
      },
    },
  },
}

捆绑的 `xai` 插件还为实时通话音频
注册了一个实时转写提供程序。

- 端点：xAI WebSocket `wss://api.x.ai/v1/stt`
- 默认编码：`mulaw`
- 默认采样率：`8000`
- 默认端点检测：`800ms`
- 中间转写结果：默认启用

Voice Call 的 Twilio 媒体流发送 G.711 mu-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`。

捆绑的 `xai` 插件通过共享的 `registerRealtimeVoiceProvider` 契约，
为 Talk 模式注册 Grok Voice Agent 实时会话。

- 端点：`wss://api.x.ai/v1/realtime?model=<voice-model>`
- 默认模型：`grok-voice-latest`
- 默认语音：`eve`
- 传输：`gateway-relay`（iOS、Android 和 Control UI 中继路径）
- 音频：PCM16 24 kHz 或 G.711 µ-law 8 kHz
- 打断：xAI 服务器 VAD 会中断响应；OpenClaw 会清除排队中的播放
  并截断未播放的提供程序历史

在 Gateway 上配置 Talk：

```json5
{
  talk: {
    realtime: {
      provider: "xai",
      mode: "realtime",
      transport: "gateway-relay",
      brain: "agent-consult",
      providers: {
        xai: {
          model: "grok-voice-latest",
          voice: "eve",
          // Opt in only if provider-side session replay is acceptable.
          sessionResumption: false,
        },
      },
    },
  },
  env: { vars: { XAI_API_KEY: "xai-..." } },
}
```

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

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

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

| 键              | 类型    | 默认值                  | 描述                                      |
| ---------------- | ------- | ------------------------ | ------------------------------------------------ |
| `enabled`        | boolean | 对 xAI 模型自动启用 | 禁用，或对已知的非 xAI provider 选择启用 |
| `model`          | string  | `grok-4.7`               | 用于代码执行请求的模型           |
| `maxTurns`       | number  | -                        | 最大对话轮数                       |
| `timeoutSeconds` | number  | `30`                     | 请求超时时间（秒）                       |

{
  agents: {
    defaults: {
      models: {
        "xai/grok-4.5": {
          params: { responsesCompactEndpoint: false },
        },
      },
    },
  },
}