Pular para o conteúdo principal
O OpenClaw inclui um Plugin de provedor xai integrado para modelos Grok. Para a maioria dos usuários, o caminho recomendado é o OAuth do Grok com uma assinatura SuperGrok ou X Premium qualificada. O OpenClaw permanece local-first: o Gateway, a configuração, o roteamento e as ferramentas são executados na sua máquina, enquanto as solicitações de modelo do Grok se autenticam pelo xAI e são enviadas para a API da xAI. O OAuth não exige uma chave de API da xAI e não exige o aplicativo Grok Build. A xAI ainda pode mostrar Grok Build na tela de consentimento porque o OpenClaw usa o cliente OAuth compartilhado da xAI.

​
Escolha seu caminho de configuração

Use o caminho que corresponde ao estado da sua instalação do OpenClaw:
1

Nova instalação do OpenClaw

Execute o onboarding com instalação do daemon quando estiver configurando um novo Gateway local e, em seguida, escolha a opção de OAuth xAI/Grok na etapa de modelo/autenticação:
openclaw onboard --install-daemon
Em um VPS ou via SSH, selecione o OAuth da xAI diretamente; o OpenClaw usa verificação por código de dispositivo e não exige um callback localhost:
openclaw onboard --install-daemon --auth-choice xai-oauth
O OAuth não exige uma chave de API da xAI. O OpenClaw não exige o aplicativo Grok Build. A xAI ainda pode rotular o aplicativo de consentimento como Grok Build porque o OpenClaw usa o cliente OAuth compartilhado da xAI.
2

Instalação existente do OpenClaw

Se o OpenClaw já estiver configurado, entre somente na xAI. Não execute novamente o onboarding completo nem reinstale o daemon apenas para conectar o Grok:
openclaw models auth login --provider xai --method oauth
Para tornar o Grok o modelo padrão depois de entrar, aplique isso separadamente:
openclaw models set xai/grok-4.3
Execute novamente o onboarding completo somente se você quiser alterar intencionalmente o Gateway, daemon, canal, workspace ou outras escolhas de configuração.
3

Caminho com chave de API

A configuração com chave de API ainda funciona para chaves do xAI Console e para superfícies de mídia que exigem configuração de provedor baseada em chave:
openclaw models auth login --provider xai --method api-key
export XAI_API_KEY=xai-...
4

Escolha um modelo

{
  agents: { defaults: { model: { primary: "xai/grok-4.3" } } },
}
O OpenClaw usa a API Responses da xAI como o transporte xAI integrado. A mesma credencial de openclaw models auth login --provider xai --method oauth ou openclaw models auth login --provider xai --method api-key também pode alimentar recursos first-class de web_search, x_search, code_execution remoto e geração de imagens/vídeos da xAI. Fala e transcrição atualmente exigem XAI_API_KEY ou configuração de provedor. web_search com Grok prefere OAuth da xAI e recorre a XAI_API_KEY ou à configuração de pesquisa na web do plugin. Se você armazenar uma chave xAI em plugins.entries.xai.config.webSearch.apiKey, o provedor de modelo xAI integrado também reutilizará essa chave como fallback. Defina plugins.entries.xai.config.webSearch.baseUrl para rotear o web_search do Grok e, por padrão, o x_search por meio de um proxy da API Responses da xAI do operador. O ajuste de code_execution fica em plugins.entries.xai.config.codeExecution.

​
Solução de problemas do OAuth

  • Para SSH, Docker, VPS ou outras configurações remotas, use openclaw models auth login --provider xai --method oauth; o OAuth da xAI usa verificação por código de dispositivo em vez de um callback localhost.
  • Se o login for bem-sucedido, mas o Grok não for o modelo padrão, execute openclaw models set xai/grok-4.3.
  • Para inspecionar perfis de autenticação xAI salvos, execute: 
    openclaw models auth list --provider xai
openclaw models status
  • A xAI decide quais contas podem receber tokens de API OAuth. Se uma conta não for qualificada, tente o caminho com chave de API ou verifique a assinatura no lado da xAI.
Use xai-oauth ao entrar via SSH, Docker ou VPS. O OpenClaw imprime uma URL da xAI e um código curto; conclua o login em qualquer navegador local enquanto o processo remoto consulta a xAI pelo token exchange concluído.

​
Catálogo integrado

O OpenClaw inclui os modelos de chat xAI atuais por padrão, ordenados do mais recente para o mais antigo nos seletores de modelo:
FamíliaIDs de modelo
Grok Build 0.1grok-build-0.1
Grok 4.3grok-4.3
Grok 4.20 Betagrok-4.20-beta-latest-reasoning, grok-4.20-beta-latest-non-reasoning
O plugin ainda resolve encaminhamentos de slugs antigos do Grok 3, Grok 4, Grok 4 Fast, Grok 4.1 Fast e Grok Code para configurações existentes. Aliases oficiais do Grok Code Fast são normalizados para grok-build-0.1; o OpenClaw não mostra mais os outros slugs upstream aposentados no catálogo selecionável.
Use grok-4.3 para chat geral e grok-build-0.1 para cargas de trabalho focadas em build/codificação, a menos que você precise explicitamente de um alias beta do Grok 4.20.

​
Cobertura de recursos do OpenClaw

O plugin integrado mapeia a superfície atual da API pública da xAI para os contratos compartilhados de provedor e ferramentas do OpenClaw. Capacidades que não se encaixam no contrato compartilhado (por exemplo, TTS em streaming e voz em tempo real) não são expostas - veja a tabela abaixo.
Capacidade da xAISuperfície do OpenClawStatus
Chat / Responsesprovedor de modelo xai/<model>Sim
Pesquisa web no servidorprovedor web_search grokSim
Pesquisa X no servidorferramenta x_searchSim
Execução de código no servidorferramenta code_executionSim
Imagensimage_generateSim
Vídeosvideo_generateSim
Texto para fala em lotemessages.tts.provider: "xai" / ttsSim
TTS em streaming-Não exposto; o contrato TTS do OpenClaw retorna buffers de áudio completos
Fala para texto em lotetools.media.audio / compreensão de mídiaSim
Fala para texto em streamingVoice Call streaming.provider: "xai"Sim
Voz em tempo real-Ainda não exposto; contrato de sessão/WebSocket diferente
Arquivos / lotesSomente compatibilidade genérica com API de modeloNão é uma ferramenta first-class do OpenClaw
O OpenClaw usa as APIs REST de imagem/vídeo/TTS/STT da xAI para geração de mídia, fala e transcrição em lote, o WebSocket de STT em streaming da xAI para transcrição de chamadas de voz ao vivo e a API Responses para ferramentas de modelo, pesquisa e execução de código. Recursos que precisam de contratos diferentes do OpenClaw, como sessões de voz em tempo real, são documentados aqui como capacidades upstream, em vez de comportamento oculto do plugin.

​
Mapeamentos de modo rápido

/fast on ou agents.defaults.models["xai/<model>"].params.fastMode: true reescreve solicitações nativas da xAI da seguinte forma:
Modelo de origemDestino do modo rápido
grok-3grok-3-fast
grok-3-minigrok-3-mini-fast
grok-4grok-4-fast
grok-4-0709grok-4-fast

​
Aliases de compatibilidade legada

Aliases legados ainda são normalizados para os IDs integrados canônicos:
Alias legadoID canônico
grok-code-fast-1grok-build-0.1
grok-code-fastgrok-build-0.1
grok-code-fast-1-0825grok-build-0.1
grok-4-fast-reasoninggrok-4-fast
grok-4-1-fast-reasoninggrok-4-1-fast
grok-4.20-reasoninggrok-4.20-beta-latest-reasoning
grok-4.20-non-reasoninggrok-4.20-beta-latest-non-reasoning

​
Recursos

O provedor de pesquisa web grok integrado prefere OAuth da xAI e, depois, recorre a XAI_API_KEY ou a uma chave de pesquisa web do plugin:
openclaw models auth login --provider xai --method oauth
openclaw config set tools.web.search.provider grok
O plugin xai integrado registra geração de vídeo por meio da ferramenta compartilhada video_generate.
  • Modelo de vídeo padrão: xai/grok-imagine-video
  • Modos: texto para vídeo, imagem para vídeo, geração com imagem de referência, edição de vídeo remoto e extensão de vídeo remoto
  • Proporções: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
  • Resoluções: 480P, 720P
  • Duração: 1-15 segundos para geração/imagem para vídeo, 1-10 segundos ao usar funções reference_image, 2-10 segundos para extensão
  • Geração com imagem de referência: defina imageRoles como reference_image para cada imagem fornecida; a xAI aceita até 7 dessas imagens
  • Tempo limite padrão da operação: 600 segundos, a menos que video_generate.timeoutMs ou agents.defaults.videoGenerationModel.timeoutMs esteja definido
Buffers de vídeo locais não são aceitos. Use URLs http(s) remotas para entradas de edição/extensão de vídeo. Imagem para vídeo aceita buffers de imagem locais porque o OpenClaw pode codificá-los como URLs de dados para a xAI.
Para usar a xAI como provedor de vídeo padrão:
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "xai/grok-imagine-video",
      },
    },
  },
}
Consulte Geração de vídeo para parâmetros de ferramenta compartilhados, seleção de provedor e comportamento de failover.
O plugin xai integrado registra geração de imagem por meio da ferramenta compartilhada image_generate.
  • Modelo de imagem padrão: xai/grok-imagine-image
  • Modelo adicional: xai/grok-imagine-image-quality
  • Modos: texto para imagem e edição com imagem de referência
  • Entradas de referência: uma image ou até cinco images
  • Proporções: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2
  • Resoluções: 1K, 2K
  • Quantidade: até 4 imagens
  • Tempo limite padrão da operação: 600 segundos, a menos que image_generate.timeoutMs ou agents.defaults.imageGenerationModel.timeoutMs esteja definido
O OpenClaw solicita à xAI respostas de imagem b64_json para que a mídia gerada possa ser armazenada e entregue pelo caminho normal de anexos do canal. Imagens de referência locais são convertidas em URLs de dados; referências remotas http(s) são repassadas.Para usar a xAI como provedor de imagem padrão:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "xai/grok-imagine-image",
      },
    },
  },
}
A xAI também documenta quality, mask, user e proporções nativas adicionais, como 1:2, 2:1, 9:20 e 20:9. Hoje, o OpenClaw encaminha apenas os controles de imagem compartilhados entre provedores; controles nativos não compatíveis são intencionalmente não expostos por meio de image_generate.
O plugin xai incluído registra texto para fala por meio da superfície de provedor tts compartilhada.
  • Vozes: eve, ara, rex, sal, leo, una
  • Voz padrão: eve
  • Formatos: mp3, wav, pcm, mulaw, alaw
  • Idioma: código BCP-47 ou auto
  • Velocidade: substituição de velocidade nativa do provedor
  • O formato nativo Opus para nota de voz não é compatível
Para usar a xAI como o provedor TTS padrão:
{
  messages: {
    tts: {
      provider: "xai",
      providers: {
        xai: {
          speakerVoiceId: "eve",
        },
      },
    },
  },
}
O OpenClaw usa o endpoint em lote /v1/tts da xAI. A xAI também oferece TTS por streaming via WebSocket, mas o contrato do provedor de fala do OpenClaw atualmente espera um buffer de áudio completo antes da entrega da resposta.
O plugin xai incluído registra fala para texto em lote por meio da superfície de transcrição de compreensão de mídia do OpenClaw.
  • Modelo padrão: grok-stt
  • Endpoint: REST da xAI /v1/stt
  • Caminho de entrada: upload de arquivo de áudio multipart
  • Compatível no OpenClaw em qualquer lugar onde a transcrição de áudio de entrada use tools.media.audio, incluindo segmentos de canais de voz do Discord e anexos de áudio de canais
Para forçar a xAI para transcrição de áudio de entrada:
{
  tools: {
    media: {
      audio: {
        models: [
          {
            type: "provider",
            provider: "xai",
            model: "grok-stt",
          },
        ],
      },
    },
  },
}
O idioma pode ser fornecido pela configuração de mídia de áudio compartilhada ou pela solicitação de transcrição por chamada. Dicas de prompt são aceitas pela superfície compartilhada do OpenClaw, mas a integração STT REST da xAI encaminha apenas arquivo, modelo e idioma, porque eles mapeiam claramente para o endpoint público atual da xAI.
O plugin xai incluído também registra um provedor de transcrição em tempo real para áudio de chamadas de voz ao vivo.
  • Endpoint: WebSocket da xAI wss://api.x.ai/v1/stt
  • Codificação padrão: mulaw
  • Taxa de amostragem padrão: 8000
  • Endpointing padrão: 800ms
  • Transcrições intermediárias: habilitadas por padrão
O stream de mídia da Twilio do Voice Call envia quadros de áudio G.711 µ-law, então o provedor xAI pode encaminhar esses quadros diretamente, sem transcodificação:
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "xai",
            providers: {
              xai: {
                apiKey: "${XAI_API_KEY}",
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}
A configuração pertencente ao provedor fica em plugins.entries.voice-call.config.streaming.providers.xai. As chaves compatíveis são apiKey, baseUrl, sampleRate, encoding (pcm, mulaw ou alaw), interimResults, endpointingMs e language.
Este provedor de streaming é para o caminho de transcrição em tempo real do Voice Call. Atualmente, a voz do Discord grava segmentos curtos e usa o caminho de transcrição em lote tools.media.audio.
O plugin xAI incluído expõe x_search como uma ferramenta do OpenClaw para pesquisar conteúdo do X (antigo Twitter) via Grok.Caminho de configuração: plugins.entries.xai.config.xSearch
ChaveTipoPadrãoDescrição
enabledboolean-Habilitar ou desabilitar x_search
modelstringgrok-4-1-fastModelo usado para solicitações x_search
baseUrlstring-Substituição da URL base de Responses da xAI
inlineCitationsboolean-Incluir citações em linha nos resultados
maxTurnsnumber-Máximo de turnos de conversa
timeoutSecondsnumber-Tempo limite da solicitação em segundos
cacheTtlMinutesnumber-Tempo de vida do cache em minutos
{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true,
            model: "grok-4-1-fast",
            baseUrl: "https://api.x.ai/v1",
            inlineCitations: true,
          },
        },
      },
    },
  },
}
O plugin xAI incluído expõe code_execution como uma ferramenta do OpenClaw para execução remota de código no ambiente sandbox da xAI.Caminho de configuração: plugins.entries.xai.config.codeExecution
ChaveTipoPadrãoDescrição
enabledbooleantrue (se a chave estiver disponível)Habilitar ou desabilitar a execução de código
modelstringgrok-4-1-fastModelo usado para solicitações de execução de código
maxTurnsnumber-Máximo de turnos de conversa
timeoutSecondsnumber-Tempo limite da solicitação em segundos
Esta é execução remota no sandbox da xAI, não exec local.
{
  plugins: {
    entries: {
      xai: {
        config: {
          codeExecution: {
            enabled: true,
            model: "grok-4-1-fast",
          },
        },
      },
    },
  },
}
  • A autenticação da xAI pode usar uma chave de API, variável de ambiente, fallback de configuração de plugin ou OAuth com uma conta xAI qualificada. O OAuth usa verificação por código de dispositivo sem callback localhost. A xAI decide quais contas podem receber tokens de API OAuth, e a página de consentimento pode mostrar Grok Build mesmo que o OpenClaw não exija o app Grok Build.
  • Atualmente, o OpenClaw não expõe a família de modelos multiagente da xAI. A xAI fornece esses modelos por meio da API Responses, mas eles não aceitam as ferramentas do lado do cliente ou personalizadas usadas pelo loop de agente compartilhado do OpenClaw. Consulte as limitações multiagente da xAI.
  • A voz em tempo real da xAI ainda não está registrada como um provedor do OpenClaw. Ela precisa de um contrato de sessão de voz bidirecional diferente de STT em lote ou transcrição por streaming.
  • quality de imagem, mask de imagem e proporções extras apenas nativas da xAI não são expostas até que a ferramenta compartilhada image_generate tenha controles correspondentes entre provedores.
  • O OpenClaw aplica automaticamente correções de compatibilidade de esquema de ferramentas e chamadas de ferramenta específicas da xAI no caminho do runner compartilhado.
  • Solicitações nativas da xAI usam tool_stream: true por padrão. Defina agents.defaults.models["xai/<model>"].params.tool_stream como false para desabilitá-lo.
  • O wrapper xAI incluído remove flags de esquema de ferramenta estritas não compatíveis e chaves de payload de esforço de raciocínio antes de enviar solicitações nativas da xAI. Apenas grok-4.3 / grok-4.3-* anunciam esforço de raciocínio configurável; todos os outros modelos da xAI com capacidade de raciocínio ainda solicitam include: ["reasoning.encrypted_content"] para que o raciocínio criptografado anterior possa ser reproduzido em turnos de acompanhamento.
  • web_search, x_search e code_execution são expostos como ferramentas do OpenClaw. O OpenClaw habilita o recurso integrado específico da xAI de que precisa dentro de cada solicitação de ferramenta, em vez de anexar todas as ferramentas nativas a cada turno de chat.
  • O web_search do Grok lê plugins.entries.xai.config.webSearch.baseUrl. x_search lê plugins.entries.xai.config.xSearch.baseUrl e depois usa como fallback a URL base de pesquisa na web do Grok.
  • x_search e code_execution pertencem ao plugin xAI incluído, em vez de serem codificados diretamente no runtime de modelo principal.
  • code_execution é execução remota no sandbox da xAI, não exec local.

​
Testes ao vivo

Os caminhos de mídia da xAI são cobertos por testes unitários e suítes ao vivo opt-in. Exporte XAI_API_KEY no ambiente do processo antes de executar probes ao vivo. 
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
O arquivo ao vivo específico do provedor sintetiza TTS normal, TTS PCM adequado para telefonia, transcreve áudio por STT em lote da xAI, transmite o mesmo PCM por STT em tempo real da xAI, gera saída de texto para imagem e edita uma imagem de referência. O arquivo ao vivo de imagem compartilhado verifica o mesmo provedor xAI por meio do caminho de seleção de runtime, fallback, normalização e anexo de mídia do OpenClaw.

​
Relacionado

Seleção de modelo

Escolha de provedores, referências de modelo e comportamento de failover.

Geração de vídeo

Parâmetros da ferramenta de vídeo compartilhada e seleção de provedor.

Todos os provedores

A visão geral mais ampla dos provedores.

Solução de problemas

Problemas comuns e correções.