Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

O OpenClaw inclui um plugin de provedor xai integrado para modelos Grok.

​
Primeiros passos

1

Crie uma chave de API

Crie uma chave de API no console da xAI.
2

Defina sua chave de API

Defina XAI_API_KEY ou execute:
openclaw onboard --auth-choice xai-api-key
3

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 chave de API de openclaw onboard --auth-choice xai-api-key também pode acionar x_search de primeira classe e code_execution remoto; XAI_API_KEY ou a configuração de busca na web do plugin também pode acionar web_search baseado em Grok. Se você armazenar uma chave xAI em plugins.entries.xai.config.webSearch.apiKey, o provedor de modelo xAI integrado também reutiliza essa chave como fallback. Defina plugins.entries.xai.config.webSearch.baseUrl para rotear web_search do Grok e, por padrã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.

​
Catálogo integrado

O OpenClaw inclui estas famílias de modelos xAI prontas para uso:
FamíliaIDs de modelo
Grok 3grok-3, grok-3-fast, grok-3-mini, grok-3-mini-fast
Grok 4.3grok-4.3
Grok 4grok-4, grok-4-0709
Grok 4 Fastgrok-4-fast, grok-4-fast-non-reasoning
Grok 4.1 Fastgrok-4-1-fast, grok-4-1-fast-non-reasoning
Grok 4.20 Betagrok-4.20-beta-latest-reasoning, grok-4.20-beta-latest-non-reasoning
Grok Codegrok-code-fast-1
O plugin também resolve adiante IDs grok-4* e grok-code-fast* mais recentes quando eles seguem o mesmo formato de API.
grok-4.3, grok-4-fast, grok-4-1-fast e as variantes grok-4.20-beta-* são as refs Grok atuais com suporte a imagens no catálogo integrado.

​
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 por 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
Busca na web no servidorProvedor web_search grokSim
Busca 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 por streaming-Não exposto; o contrato de TTS do OpenClaw retorna buffers de áudio completos
Fala para texto em lotetools.media.audio / compreensão de mídiaSim
Fala para texto por streamingVoice Call streaming.provider: "xai"Sim
Voz em tempo real-Ainda não exposto; contrato de sessão/WebSocket diferente
Arquivos / lotesCompatibilidade apenas com API genérica de modeloNão é uma ferramenta OpenClaw de primeira classe
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 por streaming da xAI para transcrição ao vivo de chamadas de voz e a API Responses para ferramentas de modelo, busca 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 xAI nativas 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 legados

Aliases legados ainda são normalizados para os IDs integrados canônicos:
Alias legadoID canônico
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 busca na web grok integrado pode usar XAI_API_KEY ou uma chave de busca na web do plugin:
openclaw config set tools.web.search.provider grok
O plugin xai integrado registra a 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 por imagem de referência, edição de vídeo remota e extensão de vídeo remota
  • Proporções de tela: 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 por imagem de referência: defina imageRoles como reference_image para cada imagem fornecida; a xAI aceita até 7 dessas imagens
Buffers de vídeo locais não são aceitos. Use URLs remotas http(s) 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 xAI como o provedor de vídeo padrão:
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "xai/grok-imagine-video",
      },
    },
  },
}
Veja Geração de vídeo para parâmetros da ferramenta compartilhada, seleção de provedor e comportamento de failover.
O plugin xai integrado registra a 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-pro
  • Modos: texto para imagem e edição por imagem de referência
  • Entradas de referência: uma image ou até cinco images
  • Proporções de tela: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2
  • Resoluções: 1K, 2K
  • Quantidade: até 4 imagens
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 xAI como o 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 integrado registra texto para fala por meio da superfície compartilhada do provedor tts.
  • 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 de nota de voz Opus não é compatível
Para usar xAI como o provedor de TTS padrão:
{
  messages: {
    tts: {
      provider: "xai",
      providers: {
        xai: {
          voiceId: "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 de provedor de fala do OpenClaw atualmente espera um buffer de áudio completo antes da entrega da resposta.
O plugin xai integrado 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 com o OpenClaw sempre que a transcrição de áudio de entrada usa tools.media.audio, incluindo segmentos de canais de voz do Discord e anexos de áudio de canal
Para forçar 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 compartilhada de mídia de áudio ou por solicitação de transcrição por chamada. Dicas de prompt são aceitas pela superfície compartilhada do OpenClaw, mas a integração REST STT da xAI encaminha apenas arquivo, modelo e idioma porque eles mapeiam claramente para o endpoint público atual da xAI.
O plugin xai integrado 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: ativadas por padrão
O fluxo de mídia 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 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)Ativar ou desativar 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",
          },
        },
      },
    },
  },
}
  • Hoje, a autenticação é somente por chave de API. A chave de API pode ser armazenada em um perfil de autenticação da xAI, variável de ambiente ou configuração do Plugin; ainda não há fluxo OAuth da xAI nem fluxo de código de dispositivo no OpenClaw.
  • grok-4.20-multi-agent-experimental-beta-0304 não é compatível com o caminho normal do provedor xAI porque exige uma superfície de API upstream diferente do transporte xAI padrão do OpenClaw.
  • A voz xAI Realtime 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 da xAI, mask de imagem e proporções extras somente nativas não são expostas até que a ferramenta compartilhada image_generate tenha controles correspondentes entre provedores.
  • O OpenClaw aplica correções de compatibilidade de esquema de ferramentas e chamadas de ferramentas específicas da xAI automaticamente no caminho do runner compartilhado.
  • As solicitações nativas da xAI usam tool_stream: true por padrão. Defina agents.defaults.models["xai/<model>"].params.tool_stream como false para desativar.
  • O wrapper xAI incluído remove flags de esquema de ferramentas estritas sem suporte e chaves de payload de raciocínio antes de enviar solicitações nativas da xAI.
  • 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 recorre à URL base da pesquisa web do Grok.
  • x_search e code_execution pertencem ao Plugin xAI incluído, em vez de serem codificados diretamente no runtime principal de modelos.
  • 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 opcionais. Os comandos ao vivo carregam segredos do seu shell de login, incluindo ~/.profile, antes de verificar XAI_API_KEY. 
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 compartilhada verifica o mesmo provedor xAI pelo caminho de seleção de runtime, fallback, normalização e anexo de mídia do OpenClaw.

​
Relacionados

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.