Tutorial de configuração do Grok Build: conectar à API do NextHub

O Grok Build é o assistente de codificação em terminal lançado pela xAI. Segundo a documentação oficial, seu principal arquivo de configuração é o ~/.grok/config.toml, e com ele é possível enviar as requisições de modelo para o grupo Grok do NextHub (0.55x, canal oficial).

Etapas para conectar

1. Instalar o Grok Build

Windows (PowerShell)

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

macOS / Linux / WSL

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

Depois de concluir a instalação, abra novamente o terminal e execute o comando abaixo para confirmar que está funcional:

grok --version

2. Abrir o diretório de configuração

Windows (CMD)

start "" "%USERPROFILE%\.grok"

macOS / Linux

mkdir -p ~/.grok

Se não existir config.toml no diretório, crie manualmente um arquivo com esse mesmo nome.

3. Escrever a configuração

Escreva o conteúdo abaixo em config.toml:

[models]
default = "grok-4.6"
web_search = "grok-4.6"

[endpoints]
models_base_url = "https://api.nexthub.cc/v1"

[model."grok-4.6"]
model = "grok-4.6"
name = "Grok 4.6"
description = "Grok 4.6 via NextHub"
api_key = "sua ApiKey do NextHub"
api_backend = "responses"
context_window = 500000
supports_backend_search = false

Duas chaves de compatibilidade

supports_backend_search = false desativa a busca de back-end do Grok (o gateway não oferece esse recurso; deixá-la ativada pode causar erro porque a requisição recebe parâmetros extras de busca de back-end). Se quiser usar o comando /effort e o parâmetro --effort para ajustar o nível de raciocínio, adicione uma linha supports_reasoning_effort = true no mesmo bloco de configuração. Depois de alterar a configuração, é preciso reiniciar o Grok Build para que ela seja recarregada.

Lembre de levar /v1 na Base URL

Em models_base_url coloque o endpoint compatível com OpenAI do NextHub: https://api.nexthub.cc/v1. A API Key deve ser a chave do grupo Grok; atualmente o grupo Grok oferece as séries grok-4.5, grok-4.6, grok-4.3, grok-4.20, além de modelos como grok-build-0.1 — a lista completa vale conforme os dados em tempo real do Model Plaza.

Se você não quiser escrever a chave diretamente no arquivo de configuração, troque a linha api_key = "..." por env_key = "NEXTHUB_API_KEY" e depois configure NEXTHUB_API_KEY nas variáveis de ambiente do sistema. Atenção: em env_key vai o nome da variável de ambiente, não a chave em si.

4. Verificar a configuração

grok inspect
grok -p "responda apenas ok" -m grok-4.6

Se o grok inspect conseguir ler a configuração e o comando de teste receber a resposta ok, a conexão foi feita com sucesso.

Problemas comuns

/effort para ajustar o nível de raciocínio não funciona

O modelo não declara supports_reasoning_effort = true (veja "Duas chaves de compatibilidade" acima), então o comando /effort e o parâmetro --effort não surtem efeito para esse modelo. Depois de alterar a configuração, é preciso reiniciar o Grok Build para que ela seja recarregada.

Aviso de modelo inexistente ou sem permissão

Verifique nesta ordem: se a ApiKey é do grupo Grok, se models_base_url é https://api.nexthub.cc/v1, se model é igual ao ID que está na lista de modelos e se a chave foi copiada por completo (sem espaços sobrando antes ou depois).