Grok CLI y Grok Build: instalación y configuración API

“Grok CLI” puede referirse a dos herramientas distintas:

• Grok Build, el coding agent oficial de xAI;
• Grok CLI comunitario, un proyecto open source sin relación con xAI.

En pruebas en macOS con un modelo GPT, Community Grok CLI 1.1.7 devolvió OK en las solicitudes de texto, pero la prueba de lectura de archivos no se completó correctamente. Grok Build 1.0.67 completó solicitudes de texto y llamadas a herramientas de lectura de archivos con api_backend = "chat_completions"; su flujo de Responses falló al analizarse en el cliente (consulta Grok Build). Ambas configuraciones usan BetterToken API Key, Base URL y Model ID.

Las dos herramientas usan el comando grok. Si instalas ambas, se ejecutará la primera versión encontrada en PATH.

Diferencias entre Grok CLI y Grok Build

Elemento	Grok Build oficial	Grok CLI comunitario
Mantenedor	xAI	superagent-ai/grok-cli, sin relación con xAI
Ideal para	Quienes buscan el agente de codificación oficial de xAI	Quienes quieren llamar a un modelo mediante una Base URL personalizada
Autenticación	Inicio de sesión en el navegador o XAI_API_KEY	GROK_API_KEY
Base URL personalizada	En ~/.grok/config.toml	Con GROK_BASE_URL
Modelo	Alias en la configuración	GROK_MODEL
Llamar modelos mediante BetterToken	Solicitudes de texto y llamadas de lectura de archivos completadas (1.0.67, chat_completions)	El texto devolvió OK; falló la prueba de lectura de archivos (1.1.7)
Comando	grok	grok

La verificación cubre solicitudes de modelos de texto y código, no llamadas a herramientas ni APIs exclusivas de xAI.

Usar Grok CLI comunitario con BetterToken

Estos comandos sirven para macOS, Linux y WSL. La instalación nativa en Windows no se ha verificado para el cliente comunitario.

Instalación

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

Si ya tienes Bun:

bun add -g grok-dev

El paquete anterior @vibe-kit/grok-cli ya no es la vía de instalación recomendada en el README actual del proyecto.

Configurar BetterToken

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

Sustituye YOUR_MODEL_ID por el Model ID completo de la model plaza y usa tu BetterToken API Key.

Verificar la conexión

grok -p "Reply with only: OK"

Solo una respuesta del modelo confirma que la API Key, la Base URL y el Model ID funcionan. Reinicia el cliente después de cambiar variables de entorno.

Community Grok CLI 1.1.7 devolvió OK en los tres intentos de texto, pero el cliente notificó errores de validación del flujo: rechazó delta.role: null al final del flujo y también informó errores de esquema en fragmentos de continuación de llamadas a herramientas. La prueba de lectura de archivos no se completó correctamente. Usa este cliente solo para solicitudes de texto dentro del alcance probado; las llamadas de lectura de archivos no han superado la prueba.

Una sesión abierta de Grok CLI no vuelve a cargar automáticamente las variables de entorno. Cierra y reinicia el cliente después de cambiar la configuración.

Cambiar de modelo

Asigna a GROK_MODEL otro Model ID completo, reinicia Grok CLI y repite la solicitud breve.

Grok Build oficial

Grok Build es el agente de codificación oficial para terminal de xAI. Admite una TUI interactiva, ejecución sin interfaz y ACP.

Instalación y autenticación

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 una cuenta o API Key de xAI

Al iniciarse por primera vez, Grok Build abre un navegador para autenticarse. Para entornos sin navegador, xAI documenta XAI_API_KEY:

export XAI_API_KEY="YOUR_XAI_API_KEY"
grok

Opcional: configurar BetterToken en Grok Build

Grok Build admite modelos personalizados compatibles con OpenAI mediante Base URL, Model ID, variable de entorno de autenticación y protocolo de solicitud.

[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 es un nombre de variable de ejemplo, no un requisito fijo de Grok Build. Grok Build lee la variable indicada en env_key.

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

Grok Build 1.0.67 completó solicitudes de texto y llamadas a herramientas de lectura de archivos con api_backend = "chat_completions". Con responses, recibió un flujo HTTP 200, pero el análisis del cliente falló primero al encontrar keepalive; el flujo registrado también contenía response.metadata. Mantén chat_completions si aparece unknown variant keepalive o unknown variant response.metadata. No se probaron las APIs exclusivas de xAI.

Solicitudes auxiliares de modelos

Ambos clientes pueden enviar solicitudes auxiliares a modelos que seleccionan por su cuenta, como grok-4.20-non-reasoning en Community Grok CLI y grok-4.6 en Grok Build. En las pruebas, BetterToken respondió 503 model_not_found con No available channel para esos modelos auxiliares, mientras la solicitud del modelo principal se completó. Puedes ignorar estos errores si la solicitud principal termina correctamente; no indican que haya fallado el Model ID seleccionado.

Evitar conflictos con grok

macOS / Linux / WSL

type -a grok
grok --version

Windows PowerShell

Get-Command grok -All
grok --version

type -a grok y Get-Command grok -All muestran todos los comandos con el mismo nombre. Elimina el cliente que no uses o ajusta PATH si tienes ambos instalados.

Errores frecuentes

Problema	Qué comprobar
Tras instalarlo se inicia el cliente Grok equivocado	Enumera todos los comandos grok y comprueba sus rutas y versiones.
Grok Build falla con unknown variant response.metadata	Asigna api_backend = "chat_completions" al modelo de BetterToken y vuelve a ejecutar grok inspect.
Grok Build oficial abre un navegador	Es el flujo de inicio de sesión predeterminado de Grok Build. Continúa con xAI; para BetterToken, configura un modelo personalizado.
401 o Unauthorized	Un modelo personalizado de Grok Build lee la variable indicada por env_key; el cliente comunitario lee GROK_API_KEY. Define solo la variable que usa el cliente actual.
model not found	Copia el Model ID completo de la model plaza y reinicia el cliente.
Las solicitudes siguen yendo a xAI	Comprueba GROK_BASE_URL en el cliente comunitario. En Grok Build, ejecuta grok inspect para comprobar base_url y el alias de modelo activo.
No funciona una función exclusiva de xAI	BetterToken solo procesa las solicitudes de modelo descritas aquí. Usa la API oficial de xAI para X Search, voz y funciones multimedia.

• Compara todas las herramientas compatibles
• Errores de API, códigos de estado y límites de solicitudes

Modelos y límites funcionales

Copia de la model plaza un Model ID completo compatible con llamadas OpenAI. Una Base URL configurable no confirma por sí sola que sean compatibles las solicitudes, las llamadas a herramientas o el formato de contexto de una familia de modelos.

Esta página solo cubre solicitudes de texto y código. Esta configuración no proporciona X Search, transcripción de voz, generación de imágenes o vídeo ni otras APIs exclusivas de xAI.

Fuentes

• model plaza de BetterToken

• Grok Build: descripción oficial

• Grok Build: Settings Reference

• Grok CLI comunitario: repositorio

• Protocolos de BetterToken