# Grok Setup Tutorial: Grok Build, Cline, Codex and CC Switch

> Connect Grok with a Passion8 API key through Cline, Grok Build or Codex. Configure the base URL, config.toml and CC Switch, then verify requests and troubleshoot.

URL: https://docs.passion8.cc/en/docs/grok
Language: en
Publisher: Passion8
Last updated: 2026-10-11

To use Grok through Passion8, you need a **Passion8 API key, an enabled model ID and `https://passion8.cc/v1`**. Use Cline for VS Code; official Grok Build and existing Codex users can follow the configuration-file guides on this page. An xAI account or official OAuth login is not required for this gateway setup.

## Choose your workflow

| Scenario | Guide | Connection |
| --- | --- | --- |
| Code, read files and review diffs in VS Code | [Cline editor setup](https://docs.passion8.cc/en/docs/grok/vscode) | Passion8 URL, key and model; no xAI login |
| Call Grok from your application | [Grok API and SDK](https://docs.passion8.cc/en/docs/grok/api) | OpenAI compatible Chat / Responses |
| Complete a reviewable small change | [Grok coding workflow](https://docs.passion8.cc/en/docs/grok/workflow) | Rules, plan, edits and tests |
| Use official Grok Build or an existing Codex client | Detailed steps below | Manual configuration or CC Switch |

Cline is a third-party editor client. The verified xAI official coding entry is Grok Build with TUI, headless and ACP. A marketplace extension sharing the Grok name does not establish xAI authorship.

There are two ways to connect Grok models through Passion8:

| Method | Best fit | Configuration |
| --- | --- | --- |
| Official xAI Grok Build CLI | Native `grok` TUI, headless and agent commands | `~/.grok/config.toml` |
| Codex CLI / Codex App | Keep the Codex workflow while changing the model to Grok | `~/.codex/auth.json` and `~/.codex/config.toml`, or CC-Switch's GPT provider |

Both use `https://passion8.cc/v1`. Examples use `grok-4.7`; select an ID actually available in the [console model catalog](https://passion8.cc).




Grok Build and Codex are different clients. Grok Build reads `~/.grok/config.toml`; Codex reads `~/.codex/auth.json` and `~/.codex/config.toml`. Do not mix their configuration files.




## Method 1: official Grok Build CLI

This guide preserves the original Grok Build v0.2.93 integration steps and updates them against official installation, custom-model and Grok 4.7 documentation checked on 2026-10-11. Check your version with `grok --version`. If fields change, use `grok inspect` to see discovered configuration, model and authentication sources.

### Install Grok CLI





### macOS / Linux / WSL


Run the official installation script:

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




### Windows


Run the official installation script in PowerShell:

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







Open a new terminal and check the command:

```bash
which grok
grok --version
```

On macOS / Linux / WSL, `which grok` usually points to `~/.local/bin/grok`, linked to `~/.grok/bin/grok`. On Windows use `Get-Command grok` instead of `which`.




If macOS / Linux / WSL reports `grok: command not found`, add `~/.local/bin` to PATH and reopen the terminal:




```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

Update with:

```bash
grok update
```

### Prepare the connection

| Item | Value |
| --- | --- |
| Passion8 API key | Create under Tokens and copy the complete key |
| Base URL | `https://passion8.cc/v1` |
| Model ID | Use the [console catalog](https://passion8.cc); this example uses `grok-4.7` |
| Configuration file | `~/.grok/config.toml` |

Check your executable and version:

```bash
which grok
grok --version
```

Paths under `~/.local/bin/grok` or `~/.grok/bin/grok` are typical for Grok Build; check the version and installation source as well.

### Recommended configuration

Store the key in `api_key`:

```toml
[model.passion8-grok]
model = "grok-4.7"
base_url = "https://passion8.cc/v1"
name = "grok-4.7"
context_window = 500000
api_key = "sk-YOUR_PASSION8_API_KEY"

[models]
default = "passion8-grok"
```




`default` is the section alias from `[model.passion8-grok]`, not the upstream model ID. The ID is the `model` value.







The original Build version displayed a default 200,000-token context for custom models without `context_window`. The current official Grok 4.7 page lists 500,000 tokens, so `500000` matches that model. Check other models separately. Restart or use `/new` before reviewing `/context` again.




### Use an environment variable instead

To keep the key out of config.toml, set `env_key` to the variable's name:

```toml
[model.passion8-grok]
model = "grok-4.7"
base_url = "https://passion8.cc/v1"
name = "grok-4.7"
context_window = 500000
env_key = "PASSION8_API_KEY"

[models]
default = "passion8-grok"
```

Then configure your shell:

```bash
echo 'export PASSION8_API_KEY="sk-YOUR_PASSION8_API_KEY"' >> ~/.zshrc
source ~/.zshrc
```

### Test the gateway

Check the key, endpoint and model availability with curl:

```bash
curl -s https://passion8.cc/v1/models \
  -H "Authorization: Bearer $PASSION8_API_KEY"
```

Then make a short request:

```bash
curl -s https://passion8.cc/v1/chat/completions \
  -H "Authorization: Bearer $PASSION8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "messages": [{"role": "user", "content": "reply with OK"}],
    "max_tokens": 10
  }'
```

If curl works but `grok` opens browser OAuth, inspect `~/.grok/config.toml`.

### Verify Grok CLI

```bash
grok -p "Reply with exactly: RELAY_OK"
```

After receiving the answer, check the matching timestamp, model and usage in Passion8. The answer alone does not prove which endpoint handled the request.

### Common errors

| Symptom | Cause to check | Fix |
| --- | --- | --- |
| Browser OAuth despite gateway settings | No usable key or default model | Check `api_key` / `env_key` and `[models].default` |
| `env_key = "sk-..."` | Actual key used instead of variable name | Use `api_key`, or put a variable name in `env_key` |
| `default = "grok-4.7"` | Model ID used instead of section alias | Use `default = "passion8-grok"` |
| `/context` displays 200k | Missing custom context setting | Add the verified model limit and restart |
| `GROK_BASE_URL` / `GROK_API_KEY` ignored | Community-client settings used | Configure official Build through `~/.grok/config.toml` |
| curl works but CLI fails | Local configuration not selected | Inspect discovered sources and authentication with `grok inspect` |

### Authentication precedence

The original version's troubleshooting record observed:

```text
model.api_key > model.env_key > current login session > XAI_API_KEY
```

If `api_key` is missing and `env_key` is incorrect, the client may fall back to a login session or open browser OAuth. Recheck behavior after client upgrades.

### Common commands

```bash
grok                         # Interactive TUI
grok "Explain this project"  # TUI with an initial instruction
grok -p "Explain auth"       # Run once, print and exit
grok logout                  # Sign out to remove an old session
grok inspect                 # Inspect configuration sources
grok --version               # Show version
```




Do not publish config.toml, shell configuration or screenshots containing keys. Create a separate Passion8 key for Grok so it can be revoked independently.




## Method 2: use Grok through Codex CLI / App

You can retain the Codex workflow and select Passion8's enabled Grok model. The client remains Codex while requests target Grok.


**Why does it still identify itself as GPT?**

Codex supplies its own system and identity instructions, so the assistant may still say GPT or Codex. Do not infer the backend from self-identification, speed or style. Check Passion8 usage and model billing records.







Do not copy every field from a normal GPT provider configuration. Grok or the Responses-compatible route may reject some parameters. Start with the configuration below.




### Configure through CC-Switch

Select the GPT / Codex provider area, add a provider and enter:

| Field | Value |
| --- | --- |
| Provider name | `custom` or `Passion8 Grok` |
| API Base URL | `https://passion8.cc/v1` |
| API key | Your Passion8 key |
| Model | `grok-4.7`, if enabled for your account |

Check that CC-Switch manages the Codex files:

| File | Purpose |
| --- | --- |
| `auth.json` | Stores `OPENAI_API_KEY` |
| `config.toml` | Provider, model, wire_api, base_url and context budget |

Manual and CC-Switch configurations should use the same verified fields. No machine-specific model_catalog_json path is needed here.

### auth.json

```json
{
  "OPENAI_API_KEY": "sk-YOUR_PASSION8_API_KEY"
}
```

### config.toml

```toml
model_provider = "custom"
model = "grok-4.7"
model_reasoning_effort = "high"
model_context_window = 500000
model_auto_compact_token_limit = 475000

[model_providers]
[model_providers.custom]
name = "custom"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://passion8.cc/v1"
```




The official Grok 4.7 page lists 500,000 tokens. The 500000 context budget and 475000 compaction threshold are client settings, not a guarantee of every gateway channel's limit. `high` is supported; the old `none` value is absent from this model's current supported list. Verify the saved file rather than allowing a catalog with an inflated window to delay compaction. Use `/compact` manually when needed.




### Manual configuration

Without CC-Switch, write the same auth.json and config.toml files with the same verified budget.





### macOS


Files:

```text
~/.codex/auth.json
~/.codex/config.toml
```

Test:

```bash
codex "Reply with: GROK_RELAY_OK"
```




### Windows


Files:

```powershell
$env:USERPROFILE\.codex\auth.json
$env:USERPROFILE\.codex\config.toml
```

Test:

```powershell
codex "Reply with: GROK_RELAY_OK"
```







Codex App uses the same configuration. After saving the provider, reopen the app or start a new session and test.

## Accounts, charges and troubleshooting

Create an account and token through the [quickstart](https://docs.passion8.cc/en/docs/quickstart). See [billing](https://docs.passion8.cc/en/docs/billing); official client subscriptions and Passion8 API balances are separate. For authentication, endpoint and model errors, see the [FAQ](https://docs.passion8.cc/en/docs/faq). Actual models and rates follow the console.

## Verified sources

Checked 2026-10-11. The official catalog contains `grok-4.7`, with `low`, `medium`, `high` and `xhigh` reasoning efforts. Gateway access follows the console.

- [Grok Build installation and custom models](https://docs.x.ai/build/overview)
- [Grok 4.7 fields and context](https://docs.x.ai/developers/models/grok-4.7)

The current overview confirms `model`, `base_url`, `name`, `env_key` and `[models].default`. The direct api_key setting, authentication order and 200k display default come from the original version's integration record; verify them with `grok inspect` after upgrades.