xAI

內建的 grok 網頁搜尋供應商會優先使用 xAI OAuth，然後才回退至 XAI_API_KEY 或外掛網頁搜尋金鑰：

openclaw models auth login --provider xai --method oauthopenclaw 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
• 輸入路徑：多部分音訊檔案上傳
• 模型選擇：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
• 暫時轉錄：預設啟用

Voice Call 的 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 會清除排隊等候的播放內容， 並截斷尚未播放的提供者歷程記錄

在閘道上設定 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-..." },}

當 Voice Call 或共用即時選擇器重複使用相同的提供者對應時， 提供者擁有的設定也會從 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 權杖，而且即使 OpenClaw 不需要 Grok Build 應用程式，同意頁面仍可能顯示 Grok Build。
• OpenClaw 目前未開放 xAI 多代理模型系列。xAI 透過 Responses API 提供這些模型，但它們不接受 OpenClaw 共用代理程式迴圈所使用的用戶端工具或自訂工具。請參閱 xAI 多代理限制。
• xAI Realtime 語音目前僅開放閘道轉送的 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 請求之前，移除不支援的 contains-count 結構描述界限，以及不支援的推理 effort 酬載鍵。Grok 4.5 支援 low、medium 和 high effort（預設為 high）。Grok 4.3 支援 none、low、medium 和 high effort（預設為 low）。其他具備推理能力的 xAI 模型不提供可設定的 effort 控制項，但仍會請求 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 網頁搜尋的基礎 URL。
• x_search 和 code_execution 由內附的 xAI 外掛管理，而非硬式編碼於核心模型執行階段。
• code_execution 是在遠端 xAI 沙箱中執行，而非本機 exec。