---
title: "xAI / Grok"
description: "Claude Code 추론을 xAI의 Grok으로 라우팅하기 — SuperGrok / X Premium+ 구독(grok 프로바이더, OAuth) 또는 xAI 개발자 API(xai 프로바이더, API 키) 중 하나로."
image: "https://shunt-docs.pages.dev/og.png"
---

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

# xAI / Grok

두 개의 내장 프로바이더가 Claude Code를 xAI의 **Grok** 모델로 라우팅합니다. 이 둘은 오직 **인증 방식과
어떤 xAI 표면에 도달하는지**만 다릅니다 — 하나를 고르세요:

| 프로바이더 | 인증 | 백엔드 | 과금 |
| :-- | :-- | :-- | :-- |
| **`grok`** | `xai_oauth` — 사용자의 **SuperGrok / X Premium+** 로그인 | `cli-chat-proxy.grok.com/v1` (Grok CLI 채팅 프록시) | 구독 — 토큰당 과금 없음 |
| **`xai`** | `api_key` (`XAI_API_KEY`) | `api.x.ai/v1` (개발자 API) | 측정된 API 크레딧 |

둘 다 xAI의 Responses 방언을 구사하는 **`kind = "responses"`** 프로바이더로 — 이 페이지가 미러링하는
[Codex](/ko/guides/codex/)와 동일한 변환 경로입니다. 더 깊은 주제 페이지([노력 & 컨텍스트](/ko/guides/effort-and-context/),
[모델 디스커버리](/ko/guides/model-discovery/), [프로바이더](/ko/guides/providers/))를 반복하는 대신 그쪽으로 링크합니다.

> **두 경로는 서로 교체할 수 없습니다**
>
> **구독** bearer는 오직 **`grok`** 프록시에서만 동작합니다 — 개발자 API(`api.x.ai`)는 이를 `402`
> (`personal-team-blocked:spending-limit`, *"…need a Grok subscription…"*)로 거부합니다.
> **API 키**는 오직 **`xai`**에서만 동작합니다. 보유한 자격 증명에 맞는 프로바이더로 Grok 슬러그를 라우팅하세요.

## 빠른 시작

코딩 에이전트가 대신 구성하도록 하세요. `shunt add`는 두 경로 중 어느 쪽이든 설정 블루프린트를 출력합니다(오프라인·읽기 전용이며, 구성은 에이전트가 편집하고 이 명령은 절대 편집하지 않습니다):

```bash
shunt add upstream grok --print | claude   # SuperGrok / X Premium+ 구독(OAuth)
shunt add upstream xai --print | claude    # xAI 개발자 API(XAI_API_KEY)
```

또는 아래의 수동 단계를 따르세요.

## 동작 방식

shunt는 Claude Code의 Anthropic Messages 요청을 OpenAI **Responses API**로 변환하여 xAI로 보내고,
스트리밍된 응답을 다시 변환합니다. `xai` **Responses 플레이버**(xAI가 거부하는 파라미터를 제거하고,
도구를 함수 도구로 유지)는 두 가지 방식으로 선택됩니다: **`api.x.ai` 호스트**로, 또는
**`auth = "xai_oauth"`**로(`grok` 프록시는 x.ai 호스트가 아니므로, 그 방언은 인증을 기준으로 결정됩니다).

| 측면 | `grok` (구독) | `xai` (API 키) |
| :-- | :-- | :-- |
| 엔드포인트 | `cli-chat-proxy.grok.com/v1/responses` | `api.x.ai/v1/responses` |
| 인증 | `~/.shunt/xai-auth.json`의 Grok CLI OAuth, 자동 갱신 | `Bearer $XAI_API_KEY` |
| 신원 헤더 | Grok CLI 헤더(`x-xai-token-auth`, `x-grok-client-identifier`, `x-grok-client-version`)로 프록시가 구독을 인정하도록 함 | 없음 |

> **오프-오리진 토큰 가드**
>
> `xai_oauth` 프로바이더는 구독 bearer를 **HTTPS를 통한 x.ai 또는 grok.com 호스트**에만, 그리고 오직
> `kind = "responses"`로만 보냅니다. 다른 곳을 가리키면 `shunt check`가 이를 거부합니다 — shunt는
> 임의의 `base_url`로 구독 토큰을 유출하지 않습니다.

## 경로 A — SuperGrok 구독 (`grok`)

### 1. 로그인

shunt 자체의 device-code 로그인(RFC 8628)을 실행하세요. URL과 코드를 출력하며, 어떤 기기의 브라우저에서든
승인하세요 — 루프백 콜백 서버가 없습니다:

```bash
shunt login xai
```

성공하면 shunt는 토큰을 **`~/.shunt/xai-auth.json`**에 `0600` 권한으로 기록하고 자동으로 갱신합니다(5분 만료
버퍼; xAI는 갱신할 때마다 refresh 토큰을 회전시키므로, shunt는 single-flight 락 아래에서 회전된 토큰을
저장합니다). refresh 토큰이 사라졌거나 응답에 회전된 토큰이 없으면, shunt는 `shunt login xai`를 다시
실행하라고 알려줍니다.

> **다른 인증 파일 위치**
>
> CI, 샌드박스, 또는 두 번째 계정을 위해 `$SHUNT_XAI_AUTH_FILE`로 경로를 오버라이드하세요:
>
> ```bash
export SHUNT_XAI_AUTH_FILE=/etc/shunt/xai-auth.json
```

### 2. 프로바이더 블록 (선택)

`grok`은 내장이므로 선언할 필요가 없습니다. 다음은 전체 기본값이며, 부분 테이블은 설정한 키만
오버라이드합니다(구성 맵은 깊은 병합됨):

```toml
[providers.grok]
kind = "responses"
base_url = "https://cli-chat-proxy.grok.com/v1"   # shunt가 뒤에 /responses를 붙임
auth = "xai_oauth"                                # ~/.shunt/xai-auth.json 읽기 + 자동 갱신
# effort = "high"                                  # 선택 — 추론 노력 활성화 (§ 추론 노력)
```

### 3. 모델을 `grok`으로 라우팅

```toml
[[routes]]
model = "grok-4.5"
provider = "grok"
# upstream_model = "grok-4.5"   # 선택: 다른 슬러그를 업스트림으로 전달
```

## 경로 B — xAI 개발자 API (`xai`)

### 1. 키 내보내기

```bash
export XAI_API_KEY=xai-…
```

### 2. 프로바이더 블록 (선택)

```toml
[providers.xai]
kind = "responses"
base_url = "https://api.x.ai/v1"   # shunt가 뒤에 /responses를 붙임
auth = "api_key"
api_key_env = "XAI_API_KEY"
```

### 3. 모델을 `xai`로 라우팅

```toml
[[routes]]
model = "grok-4.5"
provider = "xai"
```

> **구독이 아니라 API 크레딧이 필요합니다**
>
> `api.x.ai`는 사용자의 xAI **API** 크레딧에서 과금합니다. SuperGrok / X Premium+ 구독은 개발자 API에
> 대한 자격을 **부여하지 않습니다** — 자금이 없는 계정은 `402 Payment Required`
> (*"You have run out of credits or need a Grok subscription…"*)를 반환합니다.
> [console.x.ai](https://console.x.ai/)에서 크레딧을 추가하거나, 구독을 대신 사용하려면 **경로 A**를 쓰세요.

## 모델 슬러그

슬러그 카탈로그는 shunt의 것이 아니라 **xAI의 것**입니다 — shunt는 사용자가 라우팅하는 슬러그를 그대로
전달합니다. 현재 코딩/프런티어 슬러그는 `grok-4.5`, `grok-4.3`, `grok-build-0.1`입니다. 라우트에서
`upstream_model`을 사용하면 Claude Code env를 건드리지 않고 별칭을 실제 슬러그로 매핑할 수 있습니다. (모델
[디스커버리](/ko/guides/model-discovery/)는 사용자가 선언한 `claude-` 이름의 별칭만 노출하므로 원시 Grok
슬러그는 나열할 수 없습니다 — 아래의 `ANTHROPIC_CUSTOM_MODEL_OPTION`이나 티어 리매핑으로 접근하세요.)

## Claude Code에서 모델 선택

Grok 슬러그는 `claude-`로 시작하지 않으므로, Claude Code의 `/model` 선택기는 디스커버리에서 이들을
나열하지 않습니다. 메커니즘은 **Codex와 동일합니다** — id를 선택기에 직접 추가하세요:

```bash
export ANTHROPIC_CUSTOM_MODEL_OPTION="grok-4.5"   # [models.upstream_model], [[routes]], [[route_prefixes]] 중 하나로 해석되어야 함
```

동일한 [Codex 섹션](/ko/guides/codex/#4-claude-code에서-모델-선택)이 나머지를 그대로 다룹니다:
`model:` 프론트매터로 **서브에이전트**를 Grok 슬러그에 올리기, 그리고 세션 전체를 위해 **티어 별칭**
(`ANTHROPIC_DEFAULT_SONNET_MODEL`, …)을 Grok 슬러그로 재매핑하기.

> **미리 만들어진 에이전트**
>
> **[`shunt-xai` 플러그인](https://github.com/pleaseai/shunt/tree/main/plugins/shunt-xai)**은
> `grok-4.5` / `grok-4.3` / `grok-build-0.1`용 서브에이전트를 제공합니다 —
> `/plugin marketplace add pleaseai/shunt` 후 `/plugin install shunt-xai@shunt`로 설치하세요.
> 각 에이전트는 자신의 `model:`을 고정하므로, 그 서브에이전트만 우회하며 메인 세션은 Claude에 머뭅니다.
> 보유한 자격 증명에 따라 `shunt.toml`에서 슬러그를 `grok` 또는 `xai`로 라우팅하세요.

## 추론 노력

**Codex와 달리, Grok에서는 노력이 옵트인입니다.** 여러 Grok 모델(`grok-4*`, `grok-3`,
`grok-code-fast`, …)은 네이티브로 추론함에도 `reasoning.effort` 필드에 `400`을 반환하므로, shunt는
**사용자가 프로바이더나 라우트에 구성했을 때만**(또는 요청마다 전달할 때만) 다이얼을 보냅니다 — 그렇지
않으면 모델은 네이티브 추론을 사용합니다:

```toml
[providers.grok]
effort = "high"        # 모든 grok 트래픽에 적용

# …또는 라우트별
[[routes]]
model = "grok-4.5"
provider = "grok"
effort = "high"
```

`grok-4.5`는 `reasoning.effort`를 받아들입니다(실시간 검증됨). `400`을 반환하는 슬러그에 대해서는
`effort`를 설정하지 마세요. 전체 우선순위와 effort 테이블: [노력 & 컨텍스트](/ko/guides/effort-and-context/#추론-노력).

## 컨텍스트 윈도우

Claude Code는 매핑된 id에 대해 컨텍스트 바를 고정된 **200k**로 크기 조정합니다. Grok 슬러그의 실제
윈도우가 더 크면 올려주세요 — 값은 비-`claude-` id를 자동으로 따라갑니다:

```bash
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=256000   # 슬러그의 실제 윈도우로 설정, xAI 모델 문서 참고
```

이 값은 **전역**이며(세션당 하나의 값), 매핑된 모델 중 가장 작은 실제 윈도우에 맞추세요. 모델의 실제
윈도우를 초과하면 `prompt is too long` 오버플로 churn을 유발하기 때문입니다. 자세한 내용과
`count_tokens` 동작: [노력 & 컨텍스트](/ko/guides/effort-and-context/#매핑된-모델의-컨텍스트--사용량-표시).

## 웹 검색

Claude Code의 내장 **웹 검색은 Grok 라우트에서 동작하지 않습니다.** xAI의 Responses API는 함수 도구만
허용하므로, shunt는 `xai` 플레이버(`grok`과 `xai` 둘 다)에서 호스티드 `web_search` 도구를 제거합니다.
호스티드 웹 검색이 필요하면 [`codex` 또는 `openai` 라우트](/ko/guides/codex/#웹-검색)를 사용하세요.

## 전체 예시 (구독 경로)

`shunt.toml`:

```toml
[server]
bind = "127.0.0.1:3001"
default_provider = "anthropic"

[providers.grok]
effort = "high"     # 선택: 모든 Grok 트래픽에 추론 노력 활성화

[[routes]]
model = "grok-4.5"
provider = "grok"
```

셸(shunt와 Claude Code 모두 이 설정으로 실행):

```bash
shunt login xai                                     # 일회성 디바이스 코드 로그인
./target/release/shunt run                          # 게이트웨이 시작

export ANTHROPIC_BASE_URL=http://127.0.0.1:3001
export ANTHROPIC_CUSTOM_MODEL_OPTION="grok-4.5"     # /model 선택기에 추가
```

`/model`에서 **grok-4.5**를 선택하세요. 세션의 나머지는 모두 여전히 변경 없이 Anthropic으로 흐르며,
오직 매핑된 모델의 추론만 사용자의 SuperGrok 구독이 응답합니다.

## 문제 해결

| 증상 | 원인 / 해결 |
| :-- | :-- |
| 시작 시 `run shunt login xai` | `~/.shunt/xai-auth.json`이 없음(또는 잘못된 `$SHUNT_XAI_AUTH_FILE`). `shunt login xai`를 실행하세요. |
| `xAI refresh response missing refresh_token; run shunt login xai` | 저장된 refresh 토큰이 소비/회전되어 사라졌습니다. 다시 로그인하세요. |
| `402 … personal-team-blocked:spending-limit` / *"need a Grok subscription"* | API 크레딧 없이 **`xai`**(개발자 API) 경로에 있습니다. [console.x.ai](https://console.x.ai/)에서 크레딧을 추가하거나, 구독을 사용하려면 **`grok`**으로 라우팅하세요. |
| `403 … not authorized for API access` (구독 티어 게이트) | **`grok`** 경로에서 사용자의 구독 티어에 API 액세스가 포함되지 않습니다 — **재로그인은 도움이 되지 않습니다**. `XAI_API_KEY`를 설정하고 `xai` 경로를 사용하거나, [x.ai/grok](https://x.ai/grok)에서 업그레이드하세요. |
| `refusing to send a subscription token off-origin` (`shunt check`에서) | `xai_oauth` 프로바이더의 `base_url` 호스트가 `x.ai`/`grok.com`이 아니거나, HTTPS가 아니거나, `kind = "responses"`가 아닙니다. 블록을 수정하세요. |
| effort가 설정되었을 때 `400` | 그 Grok 슬러그가 `reasoning.effort`를 거부합니다. 해당 프로바이더/라우트에서 `effort`를 제거하세요. |
| `model <slug> is not enabled for this account` | 자격이 없는 슬러그 — xAI 카탈로그와 대조하여 슬러그를 확인하세요. |
| 웹 검색이 아무것도 반환하지 않음 | Grok 라우트에서 지원되지 않음; shunt가 도구를 제거합니다. `codex`/`openai` 라우트를 사용하세요. |

더 많은 내용은 전체 [문제 해결](/ko/reference/troubleshooting/) 레퍼런스를 참고하세요.

Source: https://shunt-docs.pages.dev/ko/guides/xai/index.mdx