xAI / Grok

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

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

빠른 시작

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

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 호스트가 아니므로, 그 방언은 인증을 기준으로 결정됩니다).

경로 A — SuperGrok 구독 (grok)

1. 로그인

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

shunt login xai

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

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

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

[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으로 라우팅

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

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

1. 키 내보내기

export XAI_API_KEY=xai-…

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

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

3. 모델을 xai로 라우팅

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

모델 슬러그

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

Claude Code에서 모델 선택

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

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

동일한 Codex 섹션이 나머지를 그대로 다룹니다: model: 프론트매터로 서브에이전트를 Grok 슬러그에 올리기, 그리고 세션 전체를 위해 티어 별칭 (ANTHROPIC_DEFAULT_SONNET_MODEL, …)을 Grok 슬러그로 재매핑하기.

추론 노력

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

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

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

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

컨텍스트 윈도우

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

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

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

웹 검색

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

전체 예시 (구독 경로)

shunt.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 모두 이 설정으로 실행):

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 구독이 응답합니다.

문제 해결

더 많은 내용은 전체 문제 해결 레퍼런스를 참고하세요.