> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Build | AI Gateway

> Route any AI Gateway model through Grok Build, xAI's official CLI. A single config entry connects Grok Build to the full Orq.ai model catalog with unified tracing and cost tracking.

## Overview

[Grok Build](https://x.ai/news/grok-build-cli) is xAI's official CLI assistant. It supports custom OpenAI-compatible endpoints via `~/.grok/config.toml`, so any model in the **AI Gateway** catalog can be reached from a single config entry without changing tooling.

## Prerequisites

* Active **Orq.ai** account
* [Orq.ai API key](/docs/ai-studio/organization/api-keys)

### Install Grok Build

<Tabs>
  <Tab title="macOS / Linux" icon="terminal">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -fsSL https://x.ai/cli/install.sh | bash
    ```
  </Tab>

  <Tab title="Windows" icon="windows">
    ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
    irm https://x.ai/cli/install.ps1 | iex
    ```
  </Tab>
</Tabs>

The installer places `grok` and `agent` in `~/.grok/bin/` and updates the user `PATH`.

## Setup

<Warning>
  Always use the `provider/model_id` format for model IDs (e.g. `anthropic/claude-sonnet-4-6`, not `claude-sonnet-4-6`). Bare IDs return a `400 invalid model format` error.
</Warning>

<Steps>
  <Step title="Edit ~/.grok/config.toml">
    Configure models with a `[models]` section and one `[model.<key>]` block per model. The example below uses Claude Sonnet 4.6 routed through **Orq.ai**:

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    [models]
    default = "orq-claude"

    [model.orq-claude]
    model = "anthropic/claude-sonnet-4-6"
    base_url = "https://api.orq.ai/v3/router"
    env_key = "ORQ_API_KEY"
    name = "Claude Sonnet 4.6 via Orq"
    context_window = 200000
    max_completion_tokens = 8192
    ```

    Replace `anthropic/claude-sonnet-4-6` with any model identifier from the **AI Gateway** catalog. To register additional models, add more `[model.<key>]` blocks and switch between them with `-m <key>`.
  </Step>

  <Step title="Export the API key">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    export ORQ_API_KEY="<orq-api-key>"
    ```

    Replace `<orq-api-key>` with the key from [Organization > API Keys](/docs/ai-studio/organization/api-keys). The `env_key` field in `config.toml` tells Grok Build which environment variable to read.
  </Step>

  <Step title="Launch Grok Build">
    Start an interactive session with the Orq-routed model:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    grok -m orq-claude
    ```

    For a headless one-shot completion:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    grok -p "<prompt>" -m orq-claude --output-format plain --sandbox off
    ```
  </Step>
</Steps>

## Configuration Reference

### config.toml fields

| Field                   | Description                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------- |
| `[models].default`      | Key of the model block to use when `-m` is not passed                                 |
| `model`                 | **AI Gateway** model identifier (e.g. `anthropic/claude-sonnet-4-6`, `openai/gpt-4o`) |
| `base_url`              | Set to `https://api.orq.ai/v3/router` for all **AI Gateway** models                   |
| `env_key`               | Name of the environment variable that holds the API key                               |
| `name`                  | Display name shown in the Grok Build UI                                               |
| `context_window`        | Context window size in tokens                                                         |
| `max_completion_tokens` | Maximum tokens in the completion                                                      |

### Adding more catalog models

Add one `[model.<key>]` block per model and use `-m <key>` to select at runtime:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[model.orq-gpt4o]
model = "openai/gpt-4o"
base_url = "https://api.orq.ai/v3/router"
env_key = "ORQ_API_KEY"
name = "GPT-4o via Orq"
context_window = 128000
max_completion_tokens = 16384
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bare `grok` resolves to a different CLI">
    If the npm package `@vibe-kit/grok-cli` is installed, the bare `grok` command may resolve to it instead of the xAI binary. Use the absolute path `~/.grok/bin/grok` or remove the npm package to restore the correct resolution.
  </Accordion>

  <Accordion title="Requests failing with 401 Unauthorized">
    Confirm the environment variable named in `env_key` is exported in the current shell and contains a valid **Orq.ai** [API key](/docs/ai-studio/organization/api-keys). Run `echo $ORQ_API_KEY` to verify.
  </Accordion>

  <Accordion title="No Traces appearing in Orq.ai">
    Confirm `base_url` is set to `https://api.orq.ai/v3/router` and `env_key` points to a valid **Orq.ai** [API key](/docs/ai-studio/organization/api-keys) (not an xAI or OpenAI key). Requests to the wrong endpoint will not appear in **Orq.ai** **Traces**.
  </Accordion>

  <Accordion title="Model not found error">
    Verify the `model` field uses the exact **AI Gateway** identifier (e.g. `anthropic/claude-sonnet-4-6`). Check the available models in [Workspace Settings → Models](https://my.orq.ai/settings/models).
  </Accordion>
</AccordionGroup>

## Verification

Launch **Grok Build** with `grok -m orq-claude` and send a prompt. The response appears in the session and the trace appears in [**Orq.ai** Traces](/docs/ai-studio/observability/traces) with the model identifier `anthropic/claude-sonnet-4-6` (or whichever model was selected).