Grok CLI 완벽 가이드 - xAI Grok 기반 오픈소스 터미널 AI 코딩 에이전트

Claude Code, Codex에 이어 터미널 기반 AI 코딩 에이전트 경쟁에 새로운 주자가 등장했습니다. Grok CLI는 xAI의 Grok 모델을 기반으로 하는 오픈소스 자율 코딩 에이전트로, 실시간 X(트위터) 검색, 이미지/영상 생성, 텔레그램 원격 제어까지 지원합니다. 커뮤니티 빌트 프로젝트로 MIT 라이선스이며, 이미 GitHub에서 2,600개 이상의 스타를 받았습니다.

이 글에서는 Grok CLI의 설치부터 핵심 기능, 실전 활용법, 그리고 기존 AI 코딩 도구와의 비교까지 종합적으로 정리합니다.

Grok CLI란?

Grok CLI는 터미널에서 직접 작동하는 AI 기반 코딩 에이전트입니다. "There are many coding agents. This is Grok’s"라는 슬로건처럼, Grok 모델 라인업 전체를 활용한 터미널 네이티브 개발 도구입니다.

설치 및 초기 설정

설치

# npm으로 글로벌 설치
npm i -g grok-dev

# 또는 개발 모드
git clone https://github.com/superagent-ai/grok-cli.git
cd grok-cli
bun install && bun run build

설치 후 실행 명령어는 grok입니다 (패키지명 grok-dev와 다름에 주의).

API 키 설정

xAI에서 API 키를 발급받아 다음 중 하나의 방법으로 설정합니다:

# 환경변수
export GROK_API_KEY=your-key-here

# 또는 프로젝트 .env 파일
echo "GROK_API_KEY=your-key-here" > .env

# 또는 CLI 플래그
grok -k your-key-here

# 또는 사용자 설정 파일
# ~/.grok/user-settings.json

필수 요구사항

• Node.js 18+
• xAI API 키 (x.ai에서 발급)
• 권장 터미널: WezTerm, Alacritty, Ghostty, Kitty (OpenTUI 호환)

핵심 기능

인터랙티브 TUI 모드

OpenTUI React 기반의 터미널 UI로, 대화형 코딩 세션을 진행합니다:

# 기본 실행
grok

# 특정 디렉터리에서 실행
grok -d /path/to/repo

# 이전 세션 이어하기
grok --session latest
grok -s <session-id></session-id>

헤드리스 모드 (CI/CD)

스크립팅과 자동화를 위한 비대화형 실행:

# 단일 프롬프트 실행
grok --prompt "run test suite"

# 최대 도구 실행 횟수 제한
grok -p "refactor auth module" --max-tool-rounds 30

# JSON 형태로 구조화된 출력
grok --prompt "summarize project state" --format json

실시간 X 및 웹 검색

Grok CLI의 가장 독특한 차별점입니다. 코딩 중에 실시간으로 X(트위터) 데이터와 웹 검색 결과를 참조할 수 있어, 최신 라이브러리 변경사항이나 커뮤니티 논의를 즉시 반영할 수 있습니다.

이미지 및 영상 생성

텍스트-이미지, 이미지 편집, 텍스트-영상, 이미지-영상 변환이 내장되어 있습니다. 생성된 파일은 로컬에 저장되므로 xAI URL 만료 후에도 재사용 가능합니다.

서브 에이전트

기본적으로 활성화된 서브 에이전트가 작업을 위임합니다. ~/.grok/user-settings.json에서 커스텀 서브 에이전트를 정의할 수 있으며, name, model, instruction 필드를 지정합니다.

MCP 서버 지원

Model Context Protocol 서버를 연결하여 외부 도구와 통합할 수 있습니다. Claude Code의 MCP 생태계와 유사한 확장성을 제공합니다.

텔레그램 원격 제어

Grok CLI의 독특한 기능 중 하나는 텔레그램 봇을 통한 원격 제어입니다. CLI가 실행되는 동안 스마트폰에서 에이전트에 지시를 내릴 수 있습니다.

설정 방법

1. 텔레그램 @BotFather에서 봇 생성, 토큰 발급
2. 설정 파일 또는 환경변수에 토큰 저장
3. grok 실행 후 TUI에서 /remote-control 이동
4. 텔레그램 봇에 /pair DM 전송 → 6자리 코드 입력

macOS에서는 Whisper.cpp를 통한 음성 메시지 트랜스크립션도 지원합니다:

brew install whisper-cpp ffmpeg

샌드박스 모드

macOS 14+ Apple Silicon 환경에서 Shuru microVM을 활용한 샌드박싱을 지원합니다. 에이전트 실행을 격리하여 안전하게 코드를 생성하고 테스트할 수 있습니다.

# 샌드박스 모드로 실행
grok --sandbox

# 또는 TUI 내에서
/sandbox

네트워크 접근, 포트 포워딩, 리소스 제한, 시크릿 주입을 설정할 수 있습니다.

Claude Code와의 비교

프로젝트 설정 파일 구조

Grok CLI는 Claude Code의 CLAUDE.md와 유사한 AGENTS.md 파일을 사용합니다. 루트부터 작업 디렉터리까지 계층적으로 인스트럭션을 적용합니다.

# 프로젝트 설정 구조
AGENTS.md                    # 프로젝트 인스트럭션 (CLAUDE.md와 동일 역할)
.grok/settings.json          # 프로젝트별 설정
~/.grok/user-settings.json   # 사용자 전역 설정 + API 키

실전 활용 시나리오

grok --prompt "review PR #42 and generate missing tests" --format json

grok daemon --background

주의사항

• 비공식 프로젝트: xAI와 제휴/보증 관계가 아닌 커뮤니티 빌트 프로젝트입니다
• API 비용: xAI API 사용량에 따라 비용이 발생합니다. 토큰 사용량 모니터링을 권장합니다
• 보안: API 키 관리에 주의하고, 프로덕션 코드는 반드시 사람이 리뷰해야 합니다
• 터미널 호환성: OpenTUI 완전 지원을 위해 WezTerm, Alacritty 등 권장 터미널 사용을 추천합니다

핵심 정리

• Grok CLI는 xAI Grok 모델 기반의 오픈소스 터미널 AI 코딩 에이전트
• 실시간 X/웹 검색과 이미지/영상 생성이 내장된 것이 최대 차별점
• 텔레그램 원격 제어로 모바일에서도 에이전트 조작 가능
• 헤드리스 모드로 CI/CD 파이프라인에 통합 가능
• AGENTS.md, MCP 서버, 서브 에이전트 등 하네스 구조 지원
• MIT 라이선스로 완전 무료, 커스터마이징 자유
• 설치 한 줄: npm i -g grok-dev

참조 링크

• Grok CLI 공식 사이트프로젝트 소개 및 설치 안내
• superagent-ai/grok-cli - GitHub소스 코드, README, 이슈 트래커
• Grok CLI 오픈소스 종합 가이드 - Apidog상세 기능 설명, 성능 최적화, 보안 고려사항
• xAI Grok 4 CLI: Actually GOOD! - AICodeKingGrok CLI 실사용 리뷰 및 데모
• GROK 4 CLI Tutorial - How To Vibe Code설치부터 실전 활용까지 튜토리얼
• Grok 4 CLI: Full Setup, Live Test & Cost Breakdown - Ray Fernando설정, 라이브 테스트, 비용 분석