Coding Agent 설정

Grok CLI와 Grok Build: 설치 및 설정

xAI 공식 Grok Build와 커뮤니티 Grok CLI의 차이를 확인하고 BetterToken API Key, Base URL, Model ID로 두 도구를 설정하세요.

“Grok CLI”는 서로 다른 두 도구를 가리킬 수 있습니다.

Grok Build — xAI 공식 coding agent
커뮤니티 Grok CLI — xAI와 관련 없는 오픈 소스 프로젝트

GPT 모델을 사용한 macOS 테스트에서 Community Grok CLI 1.1.7은 텍스트 요청에 OK를 반환했지만 파일 읽기 사례는 성공적으로 완료되지 않았습니다. Grok Build 1.0.67은 api_backend = "chat_completions"로 텍스트 요청과 파일 읽기 도구 호출을 완료했습니다. Responses 스트림은 클라이언트 파싱에 실패했습니다(Grok Build 참고). 두 구성 모두 BetterToken API Key, Base URL, Model ID를 사용합니다.

Grok CLI와 Grok Build 비교

비교	공식 Grok Build	커뮤니티 Grok CLI
관리자	xAI	`superagent-ai/grok-cli`, xAI와 무관
적합한 사용자	xAI 공식 코딩 에이전트를 원하는 사용자	사용자 지정 Base URL로 모델을 호출하려는 사용자
인증	브라우저 로그인 또는 `XAI_API_KEY`	`GROK_API_KEY`
사용자 Base URL	`~/.grok/config.toml`	`GROK_BASE_URL`
모델	설정의 alias	`GROK_MODEL`
BetterToken 모델 호출	텍스트 및 파일 읽기 도구 호출 통과(1.0.67, `chat_completions`)	텍스트에서 `OK` 반환, 파일 읽기 사례 실패(1.1.7)
명령	`grok`	`grok`

이 문서는 BetterToken을 통한 텍스트 및 코드 모델 요청만 다룹니다. X Search, 음성 전사, 이미지 생성, 동영상 생성 등 xAI 전용 API는 다루지 않습니다.

커뮤니티 Grok CLI에서 BetterToken 사용

다음 명령은 macOS, Linux, WSL용입니다. 커뮤니티 클라이언트의 Windows 네이티브 설정은 검증되지 않았습니다.

설치

curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash
grok --version

Bun이 설치되어 있다면:

bun add -g grok-dev

BetterToken 설정

export GROK_BASE_URL="https://bettertoken.ai/v1"
export GROK_API_KEY="YOUR_API_KEY"
export GROK_MODEL="YOUR_MODEL_ID"

YOUR_MODEL_ID를 모델 광장의 전체 Model ID로 바꾸고 BetterToken API Key를 사용하세요.

연결 확인

grok -p "Reply with only: OK"

모델 응답이 반환되어야 API Key, Base URL, Model ID가 작동한다고 확인할 수 있습니다. 환경 변수를 바꾼 뒤 클라이언트를 다시 시작하세요.

공식 Grok Build

Grok Build는 xAI 공식 터미널 coding agent입니다.

설치 및 로그인

macOS / Linux / WSL

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

Windows PowerShell

irm https://x.ai/cli/install.ps1 | iex
grok --version

처음 실행하면 브라우저가 열립니다. 브라우저가 없는 환경에서는 다음을 사용합니다.

export XAI_API_KEY="YOUR_XAI_API_KEY"
grok

Grok Build에서 BetterToken 설정

[model.bettertoken]
model = "YOUR_MODEL_ID"
base_url = "https://bettertoken.ai/v1"
name = "BetterToken"
env_key = "BETTERTOKEN_API_KEY"
api_backend = "chat_completions"

[models]
default = "bettertoken"

BETTERTOKEN_API_KEY는 예시 변수 이름입니다. Grok Build는 env_key에 지정된 변수를 읽습니다.

export BETTERTOKEN_API_KEY="YOUR_API_KEY"
grok inspect
grok -p "Reply with only: OK" -m bettertoken

보조 모델 요청

두 클라이언트는 Community Grok CLI의 grok-4.20-non-reasoning, Grok Build의 grok-4.6처럼 자체적으로 선택한 모델에 보조 요청을 보낼 수 있습니다. 테스트에서 주 모델 요청은 성공했지만 BetterToken은 이러한 보조 모델에 No available channel과 함께 503 model_not_found를 반환했습니다. 주 요청이 완료되면 보조 모델 오류는 무시해도 됩니다. 이 오류는 선택한 Model ID가 실패했다는 뜻이 아닙니다.

`grok` 명령 충돌 방지

macOS / Linux / WSL

type -a grok
grok --version

Windows PowerShell

Get-Command grok -All
grok --version

자주 발생하는 오류

문제	확인 사항
다른 클라이언트가 실행됨	각 `grok` 명령의 경로와 버전을 확인합니다.
Grok Build에서 `unknown variant response.metadata` 오류 발생	BetterToken 모델에 `api_backend = "chat_completions"`를 설정하고 `grok inspect`를 다시 실행하세요.
공식 Grok Build에서 브라우저가 열림	Grok Build의 기본 로그인 흐름입니다. xAI를 사용할 때는 계속 진행하고 BetterToken을 사용할 때는 사용자 지정 모델을 구성하세요.
`401` 또는 `Unauthorized`	Grok Build 사용자 지정 모델은 `env_key`로 지정된 변수를 읽고 커뮤니티 클라이언트는 `GROK_API_KEY`를 읽습니다. 현재 클라이언트에서 사용하는 변수만 설정하세요.
`model not found`	모델 광장에서 전체 Model ID를 복사한 뒤 다시 시작합니다.
요청이 xAI로 전송됨	커뮤니티 클라이언트는 `GROK_BASE_URL`을 확인하세요. Grok Build에서는 `grok inspect`를 실행해 `base_url`과 활성 모델 alias를 확인하세요.
xAI 전용 기능이 작동하지 않음	BetterToken은 여기 설명된 모델 요청만 처리합니다. X Search, 음성, 미디어 기능에는 공식 xAI API를 사용하세요.