Grok Build CLI 설치와 첫 실행 — Claude Code·Codex와 뭐가 다를까

Grok Build CLI란 — Claude Code·Codex 옆자리에 새로 들어온 도구

Grok Build CLI는 xAI가 2026년 5월 14일에 베타로 출시한 터미널 기반 AI 코딩 에이전트입니다. Claude Code, Codex CLI와 같은 카테고리에 속하는 도구로, 명령줄에서 코드를 읽고 수정하고 실행하는 작업을 AI가 직접 수행합니다.

기존에 xAI가 제공하던 grok-code-fast-1 모델은 2026년 5월 15일부로 단계적으로 종료(deprecate)되었고, 후속 모델인 grok-build-0.1로 자동 라우팅됩니다. 즉 코드 변경 없이도 기존 호출이 그대로 작동합니다. 다만 가격이 grok-4.3 기준으로 청구되기 때문에, 비용 통제가 필요한 환경이라면 명시적으로 새 모델명을 적어두는 게 안전합니다(자세한 내용은 마이그레이션 섹션에서 다룹니다).

위치를 정리하면 이렇습니다.

도구	제작사	진입 가격	인증 방식
Grok Build CLI	xAI	SuperGrok $30/월 또는 X Premium+ $40/월 (또는 API 사용량)	xAI/X 계정 OAuth 또는 API 키
Claude Code	Anthropic	Pro $20/월부터 (Max $100/월, 또는 사용량)	Anthropic 계정
Codex CLI	OpenAI	ChatGPT Plus $20/월부터 (또는 사용량)	OpenAI 계정

세 도구가 모두 비슷한 위치에 있지만, Grok Build CLI는 후발주자답게 몇 가지 차별점을 들고 나왔습니다. 가장 눈에 띄는 건 CLAUDE.md 파일을 네이티브로 인식한다는 점, 그리고 OpenRouter를 통해 Claude·GPT·로컬 LLM까지 라우팅할 수 있는 모델 유연성입니다.

Grok Build CLI 설치 — macOS와 Linux

설치 명령은 한 줄입니다.

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

설치 후 버전을 확인합니다.

grok --version

지원 OS는 macOS와 Linux만입니다. 2026년 5월 현재 Windows는 공식 지원 대상이 아닙니다. 윈도우에서 사용하려면 WSL(Windows Subsystem for Linux) 환경을 통해 우회해야 하고, 이 경우에도 일부 명령은 호환성 이슈가 생길 수 있습니다.

설치 스크립트가 셸 프로필(~/.bashrc, ~/.zshrc)에 PATH를 추가하므로, 설치 직후에는 새 터미널을 열거나 셸을 재시작해야 grok 명령이 잡힙니다.

인증 두 가지 — SuperGrok 구독 vs API 키

Grok Build CLI는 두 가지 인증 방식을 제공합니다. 두 방식의 비용 구조와 사용 시나리오가 다르므로, 자신의 작업량에 맞춰 골라야 합니다.

방법 1 — SuperGrok 또는 X Premium+ 구독(OAuth)

구독자라면 OAuth 로그인 한 번으로 끝입니다.

grok auth login

명령을 실행하면 브라우저가 열리면서 xAI/X 계정 로그인 흐름이 시작됩니다. 진입 가격은 SuperGrok 월 $30(연 $300)이고, X의 Premium+ 구독자($40/월)라면 별도 가입 없이 같은 권한이 따라옵니다. 더 큰 한도가 필요하면 SuperGrok Heavy(월 $300) 같은 상위 플랜을 선택할 수 있습니다. 토큰 한도 안에서 일정한 비용으로 쓸 수 있어, 매일 코딩 에이전트를 돌리는 개발자에게 어울리는 방식입니다.

방법 2 — API 키

가끔만 쓰거나, 팀 환경에서 사용량을 측정해야 한다면 API 키가 더 합리적입니다.

export XAI_API_KEY=xai-...

API 키는 xAI 콘솔에서 발급받습니다. 가격은 입력 토큰 100만 개당 약 $1 수준의 사용량 기반(usage-based)입니다. 1주일에 몇 번 정도만 사용한다면 이 쪽이 더 저렴할 수 있습니다.

첫 실행 — code, plan, ask 세 가지 모드

Grok Build CLI는 에이전트의 자율성을 세 단계로 나누어 제공합니다.

• code 모드 (기본값) — 파일을 읽고 수정하고 명령을 자동으로 실행합니다. 가장 빠르지만 자동 실행 범위가 가장 넓습니다.
• plan 모드 — 변경할 내용을 diff로 먼저 보여주고, 사용자의 승인을 받은 뒤에야 적용합니다.
• ask 모드 — 파일을 읽기만 하고 어떤 수정도 하지 않습니다. 코드 리뷰나 설명만 필요한 상황에 적합합니다.

처음 사용한다면 plan 모드부터 시작하는 걸 권장합니다. AI가 어떤 파일을 어디까지 건드릴지를 미리 확인할 수 있어서, 의도와 다르게 코드가 수정되는 사고를 예방할 수 있습니다.

세션 중간에 모드를 바꾸려면 슬래시 명령을 사용합니다.

/plan        # plan 모드로 전환
/model       # 사용 중인 모델 변경 (grok-build-0.1, claude-sonnet-4 등)
/compact     # 컨텍스트 압축
/cost        # 현재 세션의 토큰 사용량 확인

세션을 시작하기 전에 프로젝트 구조를 먼저 파악하고 싶다면 grok inspect 명령으로 디렉터리 트리·주요 파일을 요약해볼 수 있습니다.

기존 grok-code-fast-1 사용자라면 — 마이그레이션 체크포인트

xAI가 발표한 모델 정리 일정에 따르면, 2026년 5월 15일 오후 12시(PT)부로 grok-code-fast-1을 포함한 8개 모델이 단계적으로 종료되었습니다. grok-code-fast-1은 grok-build-0.1로 자동 라우팅되고, 다른 모델들은 대부분 grok-4.3으로 옮겨집니다. 즉 별도 작업 없이도 기존 코드가 그대로 작동합니다.

다만 자동 라우팅이라고 안심하고 두 가지 함정을 놓치면 안 됩니다.

첫째, 가격이 grok-4.3 기준으로 청구됩니다. 즉 입력 토큰 100만 개당 $1.25, 출력 토큰 100만 개당 $2.50가 적용됩니다. 기존 grok-code-fast-1의 단가를 가정하고 짠 예산이 어긋날 수 있으니, 코드의 모델 이름을 명시적으로 grok-build-0.1로 바꿔두면 가격을 더 예측 가능하게 관리할 수 있습니다.

둘째, 추론(reasoning) 설정이 기본값으로 떨어집니다. reasoning 모델은 grok-4.3 low effort로, non-reasoning은 none으로 자동 매핑되므로, 응답 품질이 미세하게 달라질 수 있습니다. 운영 환경이라면 짧은 회귀 테스트를 한 번 돌려보고 코드 안의 모델명을 정리하는 걸 권장합니다.

파일·이미지 첨부 — Codex의 답답함이 풀렸을까

Codex CLI를 써본 분이라면 한 번쯤 부딪쳤을 한계가 있습니다. 코드 파일은 디렉터리에서 잘 읽어가지만, PDF·이미지·스크린샷 같은 첨부파일을 세션에 직접 던지는 건 불가능했죠. 디자인 시안을 보여주면서 "이걸 코드로 만들어줘"라는 흐름이, Codex CLI에서는 자연스럽게 안 됩니다. 결국 텍스트로 풀어 적거나, Claude Code로 갈아타거나, 웹의 ChatGPT 화면을 따로 켜야 했습니다.

Claude Code는 이 부분에서 한 발 앞서 있었습니다. CLI 안에서 이미지와 PDF를 그대로 첨부해 컨텍스트로 쓸 수 있었고, 시안·다이어그램·에러 스크린샷을 바로 던질 수 있었습니다.

Grok Build CLI는 Claude Code 쪽에 가깝습니다. 세션 안에서 파일을 직접 첨부할 수 있고, 첨부한 그 자리에서 Q&A·추출·에이전트 작업이 가능합니다.

• 이미지: 이미지당 최대 20MiB (vision 처리)
• 문서: PDF, HTML, plain text, Excel, 구조화 데이터셋(CSV·JSON), 주요 코드 파일
• 사용 방식: 채팅 세션에 직접 첨부 → 같은 세션 안에서 해당 파일에 대한 검색·요약·추출 가능

여기에 더해 grok-build-0.1 모델 자체는 256K 토큰 컨텍스트를 지원합니다. 한 세션 안에 큰 PDF 매뉴얼이나 대형 코드베이스를 통째로 올려두고 작업하는 시나리오에서 유리한 숫자입니다.

요약하면 첨부파일 측면에서 세 도구의 위치는 이렇습니다.

도구	코드 파일 읽기	이미지 첨부	PDF·문서 첨부
Codex CLI	✅	❌	❌
Claude Code	✅	✅	✅
Grok Build CLI	✅	✅ (20MiB/장)	✅ (PDF·Excel·CSV 등)

Claude Code 사용자에게 — CLAUDE.md 네이티브 지원의 의미

Grok Build CLI가 들고 나온 차별점 중 한국 개발자에게 가장 직접적으로 의미 있는 건 CLAUDE.md 파일을 그대로 읽어들인다는 점입니다.

Claude Code를 써오던 분이라면 프로젝트 루트에 이미 CLAUDE.md 파일이 있을 가능성이 높습니다. 프로젝트 컨텍스트, 코딩 규칙, 도메인 지식이 정리된 파일이죠. 이 파일을 다른 AI 도구로 옮기려면 보통 형식을 바꾸거나 별도 import 절차가 필요했는데, Grok Build CLI는 별도 설정 없이 같은 CLAUDE.md 파일을 인식합니다.

여기에 OpenRouter 라우팅으로 claude-sonnet-4·gpt-5 같은 외부 모델까지 같은 CLI 안에서 호출할 수 있어, "도구 하나에 모델만 바꿔 끼우는" 흐름이 가능해졌습니다. 어떤 작업은 Grok 모델로, 어떤 작업은 Claude로 처리하는 식의 운용이 한 터미널에서 끝납니다.

다음 단계

이번 글은 Grok Build CLI를 처음 켜기까지의 흐름만 정리했습니다. 실제 코딩 작업을 어떻게 시키는지, 한국어 환경에서 발생하는 인코딩 이슈는 없는지 같은 실전 이슈는 후속 글에서 다룰 예정입니다.

xAI가 같은 시기에 함께 발표한 Connectors, Imagine Agent Mode, Persistent Skills까지 합치면 2026년 5월은 Grok 생태계가 가장 크게 움직인 한 달입니다. 다음 글에서는 이 5월 업데이트를 한자리에 정리해보겠습니다.