Grok Build 설정 튜토리얼: NextHub API 연동
Grok Build은 xAI가 출시한 터미널 코딩 어시스턴트입니다. 공식 문서에 따르면 주요 설정 파일은 ~/.grok/config.toml이며, 모델 요청을 NextHub의 Grok 그룹(0.55x, 공식 채널)으로 보낼 수 있습니다.
연동 단계
1. Grok Build 설치
irm https://x.ai/cli/install.ps1 | iexcurl -fsSL https://x.ai/cli/install.sh | bash설치가 끝나면 터미널을 새로 열고 아래 명령어로 정상적으로 사용할 수 있는지 확인하세요:
grok --version2. 설정 디렉터리 열기
start "" "%USERPROFILE%\.grok"mkdir -p ~/.grok디렉터리에 config.toml이 없으면 같은 이름으로 파일을 직접 만드세요.
3. 설정 작성
config.toml에 아래 내용을 작성합니다:
[models]
default = "grok-4.6"
web_search = "grok-4.6"
[endpoints]
models_base_url = "https://api.nexthub.cc/v1"
[model."grok-4.6"]
model = "grok-4.6"
name = "Grok 4.6"
description = "Grok 4.6 via NextHub"
api_key = "당신의 NextHub ApiKey"
api_backend = "responses"
context_window = 500000
supports_backend_search = false두 가지 호환성 스위치
supports_backend_search = false는 Grok 백엔드 검색을 끕니다(게이트웨이는 해당 기능을 제공하지 않으며, 끄지 않으면 요청에 백엔드 검색 파라미터가 추가되어 오류가 발생할 수 있습니다). /effort 명령어와 --effort 옵션으로 사고 단계를 조정하려면 같은 설정 블록에 supports_reasoning_effort = true 한 줄을 추가하세요. 설정을 수정한 뒤에는 Grok Build을 재시작해야 다시 로드됩니다.
Base URL에는 /v1을 붙여야 합니다
models_base_url에는 NextHub의 OpenAI 호환 엔드포인트인 https://api.nexthub.cc/v1를 입력합니다. API Key에는 Grok 그룹의 API 키를 사용하며, 현재 Grok 그룹은 grok-4.5, grok-4.6, grok-4.3, grok-4.20 시리즈와 grok-build-0.1 등의 모델을 제공합니다. 전체 목록은 모델 광장의 실시간 데이터를 기준으로 하세요.
API 키를 설정 파일에 직접 작성하고 싶지 않다면 api_key = "..." 한 줄을 env_key = "NEXTHUB_API_KEY"로 교체한 뒤, 시스템 환경 변수에 NEXTHUB_API_KEY를 설정하면 됩니다. env_key에는 환경 변수명을 입력하며, API 키 자체를 입력하는 것이 아닙니다.
4. 설정 검증
grok inspect
grok -p "ok만 답장하세요" -m grok-4.6grok inspect 명령어로 설정을 정상적으로 읽어오고, 테스트 명령어에 ok 응답이 돌아오면 연동에 성공한 것입니다.
자주 발생하는 문제
/effort로 사고 단계 조정이 적용되지 않습니다
해당 모델에 supports_reasoning_effort = true가 선언되어 있지 않으면(위의 "두 가지 호환성 스위치" 참고) /effort 명령어와 --effort 옵션이 해당 모델에 적용되지 않습니다.
모델이 존재하지 않거나 권한이 없다는 안내가 표시됩니다
다음을 순서대로 확인하세요. ApiKey가 Grok 그룹의 것인지, models_base_url이 https://api.nexthub.cc/v1인지, model이 모델 목록의 ID와 일치하는지, API 키를 완전하게 복사했는지(앞뒤에 불필요한 공백이 없는지)입니다.