Grok CLI e Grok Build: instalação e configuração de API

“Grok CLI” pode se referir a duas ferramentas diferentes:

• Grok Build, o agente de programação oficial da xAI;
• Grok CLI da comunidade, um projeto de código aberto sem vínculo com a xAI.

Nos testes em macOS com um modelo GPT, o Grok CLI da comunidade 1.1.7 retornou OK nas solicitações de texto, mas seu caso de leitura de arquivos não foi concluído com sucesso. O Grok Build 1.0.67 concluiu solicitações de texto e chamadas de ferramentas para leitura de arquivos com api_backend = "chat_completions"; o fluxo Responses falhou na interpretação pelo cliente (veja Grok Build). As duas configurações usam uma BetterToken API Key, Base URL e Model ID.

As duas ferramentas usam o comando grok. Se ambas estiverem instaladas, o terminal executará o primeiro executável encontrado no PATH, o que pode dar a impressão de que a configuração não funciona. Mantenha apenas uma versão ou instale cada uma em um ambiente separado.

Diferenças entre Grok CLI e Grok Build

Item	Grok Build oficial	Grok CLI da comunidade
Mantenedor	xAI	superagent-ai/grok-cli, sem vínculo com a xAI
Indicado para	Quem quer o agente de programação oficial da xAI	Quem quer chamar um modelo com uma Base URL personalizada
Autenticação padrão	Login pelo navegador ou XAI_API_KEY	GROK_API_KEY
Base URL personalizada	Configure em ~/.grok/config.toml	Defina GROK_BASE_URL
Modelo	Defina um alias de modelo no arquivo de configuração	Defina GROK_MODEL
Chamar modelos pelo BetterToken	Texto e chamadas de ferramentas para leitura de arquivos passaram (1.0.67, chat_completions)	Texto retornou OK; o caso de leitura de arquivos falhou (1.1.7)
Comando de inicialização	grok	grok

Este guia cobre apenas solicitações de modelos de texto e código pelo BetterToken. Não cobre APIs exclusivas da xAI, como X Search, transcrição de fala, geração de imagens ou geração de vídeos.

Usar o Grok CLI da comunidade com o BetterToken

Os comandos abaixo servem para macOS, Linux e WSL. A instalação e a configuração nativas no Windows não foram verificadas para o cliente da comunidade.

Instalar

curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash
grok --version

Se o Bun já estiver instalado, você pode usar:

bun add -g grok-dev

O pacote antigo @vibe-kit/grok-cli não é mais o método de instalação recomendado pelo README atual do projeto.

Configurar o BetterToken

export GROK_BASE_URL="https://bettertoken.ai/v1"
export GROK_API_KEY="YOUR_API_KEY"
export GROK_MODEL="YOUR_MODEL_ID"

Substitua YOUR_MODEL_ID pelo Model ID completo da model plaza. Use sua própria BetterToken API Key: cadastre-se e obtenha uma.

Verificar a conexão

grok -p "Reply with only: OK"

Somente uma resposta do modelo confirma que API Key, Base URL e Model ID estão funcionando. Iniciar o cliente, por si só, não verifica a solicitação ao modelo.

O Grok CLI da comunidade 1.1.7 retornou OK nas três tentativas de texto, mas o cliente relatou erros de validação do fluxo: rejeitou delta.role: null no final do fluxo e também relatou erros de esquema nos blocos de continuação das chamadas de ferramentas. O caso de leitura de arquivos não foi concluído com sucesso. Dentro deste escopo testado, use esse cliente apenas para solicitações de texto; as chamadas de ferramentas para leitura de arquivos não passaram.

Uma sessão aberta do Grok CLI não recarrega as variáveis de ambiente automaticamente. Saia e reinicie após alterar a configuração.

Trocar de modelo

Altere GROK_MODEL para outro Model ID completo, reinicie o Grok CLI e repita a solicitação curta.

Grok Build oficial

Grok Build é o agente de programação oficial da xAI para terminal. Oferece uma interface de terminal interativa, operação sem interface e ACP.

Instalar

macOS / Linux / WSL

curl -fsSL https://x.ai/cli/install.sh | bash
grok --version

Windows PowerShell

irm https://x.ai/cli/install.ps1 | iex
grok --version

Usar uma conta xAI ou API Key

O Grok Build abre um navegador para autenticação na primeira inicialização. A xAI documenta XAI_API_KEY para ambientes sem navegador:

export XAI_API_KEY="YOUR_XAI_API_KEY"
grok

Opcional: configurar o BetterToken no Grok Build

O Grok Build oferece suporte a modelos personalizados compatíveis com OpenAI, com Base URL, Model ID, variável de ambiente para autenticação e protocolo de solicitação.

[model.bettertoken]
model = "YOUR_MODEL_ID"
base_url = "https://bettertoken.ai/v1"
name = "BetterToken"
env_key = "BETTERTOKEN_API_KEY"
api_backend = "chat_completions"

[models]
default = "bettertoken"

BETTERTOKEN_API_KEY é um nome de variável de exemplo, não uma exigência fixa do Grok Build. O cliente lê a variável de ambiente indicada em env_key.

export BETTERTOKEN_API_KEY="YOUR_API_KEY"
grok inspect
grok -p "Reply with only: OK" -m bettertoken

O Grok Build 1.0.67 concluiu solicitações de texto e chamadas de ferramentas para leitura de arquivos com api_backend = "chat_completions". Com responses, recebeu um fluxo HTTP 200, mas falhou na interpretação pelo cliente, rejeitando primeiro keepalive; o fluxo registrado também continha response.metadata. Mantenha chat_completions se encontrar unknown variant keepalive ou unknown variant response.metadata. As APIs exclusivas da xAI não foram verificadas.

Solicitações a modelos auxiliares

Os dois clientes podem enviar solicitações auxiliares a modelos escolhidos por eles, como grok-4.20-non-reasoning no Grok CLI da comunidade e grok-4.6 no Grok Build. Nos testes, o BetterToken retornou 503 model_not_found com No available channel para esses modelos auxiliares, enquanto a solicitação ao modelo principal foi bem-sucedida. Você pode ignorar esses erros de modelos auxiliares quando a solicitação principal for concluída com sucesso; eles não significam que o Model ID selecionado falhou.

Evitar conflito com o comando grok

macOS / Linux / WSL

type -a grok
grok --version

Windows PowerShell

Get-Command grok -All
grok --version

type -a grok e Get-Command grok -All listam vários comandos com o mesmo nome. Remova o cliente que não usa ou ajuste o PATH se ambos estiverem instalados.

Erros comuns

Sintoma	O que verificar
O Grok errado é iniciado após a instalação	Liste todos os comandos grok e confira o caminho e a versão.
Grok Build falha com unknown variant response.metadata	Defina api_backend = "chat_completions" para o modelo do BetterToken e execute grok inspect novamente.
O Grok Build oficial abre um navegador	Esse é o fluxo de login padrão do Grok Build. Continue se usar a xAI; configure um modelo personalizado se usar o BetterToken.
401 ou Unauthorized	Um modelo personalizado do Grok Build lê a variável indicada em env_key; o cliente da comunidade lê GROK_API_KEY. Defina apenas a variável usada pelo cliente atual.
model not found	Copie o Model ID completo da model plaza e reinicie o cliente.
As solicitações ainda vão para a xAI	Confira GROK_BASE_URL no cliente da comunidade. Execute grok inspect no Grok Build para confirmar base_url e o alias de modelo ativo.
Um recurso exclusivo da xAI não funciona	O BetterToken processa apenas as solicitações de modelos descritas aqui. Use a API oficial da xAI para X Search, fala e mídia.

• Compare todas as ferramentas compatíveis
• Erros da API, códigos de status e limites de requisições

Modelos disponíveis e limites de recursos

Copie um Model ID completo compatível com chamadas OpenAI da model plaza. Poder configurar a Base URL, por si só, não comprova a compatibilidade das solicitações, chamadas de ferramentas ou do formato de contexto de uma família de modelos.

Esta página cobre apenas solicitações de modelos de texto e código. O BetterToken não fornece X Search, transcrição de fala, geração de imagens, geração de vídeos nem outras APIs exclusivas da xAI por esta configuração.

Fontes e guias relacionados

• Grok Build: visão geral oficial da xAI
• Grok Build: referência de configurações da xAI
• Grok CLI da comunidade: repositório atual
• Protocolos compatíveis com OpenAI e Anthropic do BetterToken
• Model plaza do BetterToken