Skip to content
Grok Build Setup
中文

Manual configuration guide

If you would rather not delegate it, or you want to understand what each step actually does, follow this. Every step below was verified against a live Grok Build install.

Prerequisite: log out of the official account

A Grok Build session outranks an API key. While a valid session exists locally, the api_key you configure will not be used — and the error you get will point you in the wrong direction.

bash
grok --version          # confirm it's installed
grok logout             # mandatory
ls ~/.grok/auth.json    # should report No such file (auth.json.lock is fine)

Step 1 — Get the real model IDs

This is the foundation. Do not assume the model is called grok-4 or grok-4.5. What the gateway serves is whatever the API says it serves.

bash
export K="sk-your-api-key"
export EP="https://your-gateway.example.com/v1"

curl -s "$EP/models" -H "Authorization: Bearer $K"
Read the model IDs from data[].id in the response
  • 401 — the key is invalid or mistyped
  • 404 — wrong path; try adding or removing the trailing /v1
  • 503 — the upstream is temporarily down; wait and retry instead of changing config

Step 2 — Smoke-test inference

A model listing is not proof that inference works. On relay gateways the two are frequently out of sync.

bash
curl -s "$EP/chat/completions" \
  -H "Authorization: Bearer $K" \
  -H "Content-Type: application/json" \
  -d '{"model":"<MODEL_ID_FROM_STEP_1>","messages":[{"role":"user","content":"hi"}],"max_tokens":20}'
Confirm a 200 with real content in choices[0].message.content

Step 3 — Write config.toml

The file lives at ~/.grok/config.toml (on Windows, %USERPROFILE%\.grok\config.toml). Back it up before editing.

toml
[endpoints]
models_base_url = "https://your-gateway.example.com/v1"

[model."grok-4.5"]
api_key = "sk-your-api-key"
context_window = 500000

[models]
default = "grok-4.5"
default_reasoning_effort = "high"
Swap the model name for a real ID from step 1

Quote model names that contain a dot

Write [model.grok-4.5] and TOML reads the dot as a separator, parsing it as 'key 5 inside table grok-4' — your api_key never lands on the model. It must be [model."grok-4.5"]. This is the single most common reason the setup fails.

The fields that matter

  • [endpoints] models_base_url — the master switch. Setting it flips Grok from session auth to Authorization: Bearer key auth, so grok login is no longer needed. Every [model.*] inherits this base_url
  • [model."..."] api_key — the key for that model. Credential resolution order is api_key → env_key → the global XAI_API_KEY
  • context_window — drives when auto-compaction kicks in; set it to your model's real window
  • [models] default — the default model; must be an ID that exists on the gateway
  • default_reasoning_effort — low / medium / high
  • [ui] fork_secondary_model — the secondary model used by fork; must also be a real model

Step 4 — Tighten permissions

The config holds your key in plaintext. Do not leave it world-readable.

bash
chmod 600 ~/.grok/config.toml

Step 5 — Verify

Writing the file is not the same as it taking effect. Verify twice: once that the config is recognised, once that inference actually runs.

bash
grok models
# expect: Model 'grok-4.5' is using its own API key.
# expect: the models you saw in step 1

grok -p "Introduce yourself in one sentence"

Seeing 'You are not authenticated'?

The config did not take effect. Check in this order: quotes around the model name → whether the logout really happened → whether base_url needs /v1. If grok models lists built-in models you never configured, it is almost certainly the quotes.

Alternative: environment variables only

If you would rather not touch the config file, or you need to switch between gateways on the fly, environment variables work too. Handy for CI and one-off runs.

bash
export GROK_MODELS_BASE_URL="https://your-gateway.example.com/v1"
export XAI_API_KEY="sk-your-api-key"
grok
grok models will now report: You are using XAI_API_KEY.
  • GROK_MODELS_BASE_URL — inference base URL; the model list is fetched from {base_url}/models
  • XAI_API_KEY — sent as Authorization: Bearer
  • GROK_MODELS_LIST_URL — override when the model list is not at {base_url}/models
  • GROK_HOME — override the default ~/.grok directory

Rolling back to the official account

Session auth and key auth are mutually exclusive, so switching back means removing the gateway config first.

bash
# 1. Remove [endpoints] models_base_url and the per-model api_key entries
# 2. Clear the environment variables
unset GROK_MODELS_BASE_URL XAI_API_KEY
# 3. Log back in
grok login