xAI

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

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

Video 1.5 还可识别 xAI 的 grok-imagine-video-1.5-preview 和 grok-imagine-video-1.5-2026-05-30 标识符。OpenClaw 会原样转发所选标识符，但应用相同的仅限图像验证。

要将 xAI 用作默认视频提供商：

{
  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、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 图像响应，以便通过常规渠道附件路径 存储和交付生成的媒体。本地参考图像会转换为数据 URL；远程 http(s) 引用 则原样传递。

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

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

内置的 xai 插件通过共享的 tts 提供商接口注册文本转语音功能。

• 语音：来自 xAI 的已认证实时目录；使用 openclaw infer tts voices --provider xai 列出
• 离线备用语音：ara、eve、leo、rex、sal
• 默认语音：eve
• 即使账户的自定义语音 ID 不在 内置目录响应中，也会将其转发
• 格式：mp3、wav、pcm、mulaw、alaw
• 语言：BCP-47 代码或 auto
• 速度：提供商原生速度覆盖值
• 不支持原生 Opus 语音消息格式

要将 xAI 用作默认 TTS 提供商：

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

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

• 端点：xAI REST /v1/stt
• 输入路径：multipart 音频文件上传
• 模型选择：xAI 在内部选择转录模型； 该端点没有模型选择器
• 用于入站音频转录读取 tools.media.audio 的所有位置， 包括 Discord 语音频道片段和渠道音频附件

要强制使用 xAI 进行入站音频转录：

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

可以通过共享音频媒体配置或每次调用的转录请求提供语言。 共享 OpenClaw 接口接受提示词提示，但 xAI REST STT 集成仅转发文件和语言， 因为只有这两项可映射到当前公开的 xAI 端点。

内置的 xai 插件还为实时语音通话音频注册了 实时转录提供商。

• 端点：xAI WebSocket wss://api.x.ai/v1/stt
• 默认编码：mulaw
• 默认采样率：8000
• 默认端点检测：800ms
• 临时转录：默认启用

语音通话的 Twilio 媒体流发送 G.711 mu-law 音频帧，因此 xAI 提供商会直接转发这些帧而不进行转码：

{
  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：

{
  talk: {
    realtime: {
      provider: "xai",
      mode: "realtime",
      transport: "gateway-relay",
      brain: "agent-consult",
      providers: {
        xai: {
          model: "grok-voice-latest",
          voice: "eve",
          // 仅当可接受提供商侧会话重放时才选择启用。
          sessionResumption: false,
        },
      },
    },
  },
  env: { XAI_API_KEY: "xai-..." },
}

当语音通话或共享实时选择器复用同一提供商映射时， 提供商自有配置也会从 plugins.entries.voice-call.config.realtime.providers.xai 解析。支持的键包括 apiKey、baseUrl、model、voice、vadThreshold、silenceDurationMs、 prefixPaddingMs、reasoningEffort 和 sessionResumption。 reasoningEffort 仅接受 high 或 none，与 xAI Voice Agent API 一致。

xAI 的服务器 VAD 始终会创建响应并处理音频中断。 请使用 consultRouting: "provider-direct"；xAI Voice Agent 协议不支持 强制转录路由和禁用输入音频中断。

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

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

{
  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

{
  plugins: {
    entries: {
      xai: {
        config: {
          codeExecution: {
            enabled: true,
            model: "grok-4.3",
          },
        },
      },
    },
  },
}

• xAI 身份验证可以使用 API 密钥、环境变量、插件配置 回退，或通过符合条件的 xAI 账户使用 OAuth。OAuth 使用设备代码 验证，无需 localhost 回调。xAI 决定哪些账户 可以获取 OAuth API 令牌，并且同意页面可能会显示 Grok Build， 即使 OpenClaw 并不需要 Grok Build 应用。
• OpenClaw 目前不公开 xAI 多智能体模型系列。xAI 通过 Responses API 提供这些模型，但它们不接受 OpenClaw 共享 Agent loop 使用的客户端工具或自定义工具。 请参阅 xAI 多智能体限制。
• xAI Realtime 语音目前仅公开 Gateway 网关中继的 Talk 传输。 Control UI 尚未接入由浏览器管理的提供商 WebSocket 会话。
• 在共享 image_generate 工具具备相应的 跨提供商控制项之前，不会公开 xAI 图像 quality、图像 mask 以及仅原生支持的额外宽高比。

• OpenClaw 会在共享运行器路径上自动应用 xAI 特定的工具架构和工具调用兼容性 修复。
• 原生 xAI 请求默认使用 tool_stream: true。将 agents.defaults.models["xai/<model>"].params.tool_stream 设置为 false 可将其禁用。
• 内置 xAI 封装器会在发送原生 xAI 请求前，移除不受支持的包含项计数架构边界 和不受支持的推理 强度 载荷键。Grok 4.5 支持低、中和 高强度（默认为高）。Grok 4.3 支持无、低、中和高 强度（默认为低）。其他支持推理的 xAI 模型不提供 可配置的强度控制，但仍会请求 include: ["reasoning.encrypted_content"]，以便在后续轮次中重放之前的加密推理。
• 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 搜索基础 URL。
• x_search 和 code_execution 由内置 xAI 插件 所有，而不是硬编码到核心模型运行时中。
• code_execution 是远程 xAI 沙箱执行，而不是本地 exec。