Gemini CLI, 무료라서 쓰면 안 되는 조건이 있습니다
하루 1,000 요청 무료라는 말만 믿고 복잡한 프로젝트에 썼다가 오전에 한도가 다 차버린 경험, 생각보다 많습니다. 공식 문서를 직접 파고들었더니 한국어 블로그가 전혀 안 건드린 구조가 보였습니다.
Gemini CLI가 뭔지 30초 요약
Gemini CLI는 구글이 만든 터미널 기반 AI 코딩 에이전트입니다. 2025년 중반 오픈소스(Apache 2.0)로 공개됐고, 2026년 3월 현재 Gemini 3 Pro까지 자동 라우팅되는 구조로 업데이트됐습니다. 터미널에서 gemini 명령어 하나로 시작하고, 프로젝트 파일 수정부터 터미널 명령 실행까지 자연어 한 줄로 지시할 수 있습니다.
설치는 간단합니다. Node.js 18+ 환경에서 아래 한 줄이면 끝납니다.
npm install -g @google/gemini-cli구글 계정으로 로그인하면 별도 결제 없이 하루 1,000 요청을 쓸 수 있고, Gemini 3 Pro 모델이 자동으로 배정됩니다. 경쟁 도구인 Claude Code(Anthropic)나 GitHub Copilot CLI가 유료 구독이 필수인 것과 대비되는 부분입니다. (출처: Gemini CLI 공식 요금 문서, geminicli.com/docs/resources/quota-and-pricing/)
무료 1,000 요청의 진짜 구조
💡 공식 문서에 적힌 “1,000 requests/day”가 실제 사용 흐름에서 어떻게 줄어드는지 놓치면 아침에 할당량이 다 사라집니다.
Gemini CLI의 “요청”은 채팅 메시지 한 줄을 뜻하는 게 아닙니다. 공식 문서와 실제 비교 분석 자료를 교차해보면, 에이전트가 실행하는 모든 도구 호출(tool call)이 각각 1건의 요청으로 계산됩니다. (출처: FreeAcademy.ai 비교 분석, 2026.02.15)
예를 들어 “이 프로젝트에서 버그를 찾아 고쳐줘”라고 요청하면:
복잡한 작업 하나에 20~50건이 나가는 건 드문 일이 아닙니다. 1,000건을 단순히 대화 횟수로 받아들이면 실제 쓸 수 있는 작업량은 훨씬 적습니다. (출처: FreeAcademy.ai Gemini CLI 분석, 2026.02.15)
⚠️ API 키 무료 플랜은 다릅니다: API 키로 인증하면 하루 요청 한도가 250건으로 줄어들고, 접근 가능한 모델이 Gemini Flash 전용으로 제한됩니다. Gemini 3 Pro 자동 라우팅은 구글 계정 로그인(Code Assist) 방식에서만 작동합니다. (출처: geminicli.com/docs/resources/quota-and-pricing/)
현재 사용량은 세션 내 /stats model 명령으로 실시간 확인할 수 있습니다.
Plan 모드가 조용히 바꿔놓는 것
2026년 3월 둘째 주, 구글 개발자 블로그가 Gemini CLI에 Plan 모드가 추가됐다고 공식 발표했습니다. 한국어 독립 포스팅은 아직 없는 내용입니다.
💡 Plan 모드를 켜면 Gemini가 코드를 건드리기 전에 읽기 전용 상태로 프로젝트 전체를 탐색하고, 실행 계획을 Markdown 파일로 정리한 뒤 승인을 기다립니다.
Plan 모드에서 허용되는 도구 목록
공식 문서에 명시된 Plan 모드의 허용 도구는 다음과 같습니다. (출처: geminicli.com/docs/cli/plan-mode/)
- 읽기 전용 파일 시스템:
read_file,list_directory,glob - 검색:
grep_search,google_web_search - 연구 서브에이전트:
codebase_investigator,cli_help - 쓰기: 계획 디렉터리(
~/.gemini/tmp/.../plans/) 안의.md파일만
그런데 여기에 숨겨진 변화가 하나 있습니다. Plan 모드가 켜지면 Gemini CLI가 자동으로 Gemini 3 Pro(고추론 모델)를 사용하고, 계획 승인 후 실행 단계로 넘어가면 자동으로 Gemini Flash(고속 모델)로 전환됩니다. 공식 문서에는 이렇게 나옵니다.
“Planning Phase: While in Plan Mode, the CLI routes requests to a high-reasoning Pro model to ensure robust architectural decisions. Implementation Phase: Once a plan is approved and you exit Plan Mode, the CLI automatically switches to a high-speed Flash model.”
— Gemini CLI 공식 문서, Automatic Model Routing (geminicli.com/docs/cli/plan-mode/)
이게 왜 중요하냐면, Plan 모드를 끄고 바로 실행 모드로 쓰면 처음부터 Flash 모델이 담당하는 경우가 생깁니다. 복잡한 리팩터링을 시킬 때 Plan 모드 없이 진행하면 비용 절감이 아니라 품질 저하가 먼저 옵니다.
Plan 모드 진입 방법 3가지
- 키보드 단축키: Shift+Tab으로 Default → Auto-Edit → Plan 순환
- 명령어: 입력창에
/plan입력 - 자연어: “이 작업 계획부터 세워줘”라고 말하면 자동 진입
승인된 계획은 Ctrl+X로 외부 에디터에서 직접 편집도 가능합니다.
무료 티어에서 데이터가 어떻게 쓰이는가
무료로 1,000 요청을 주는 대신 구글이 뭔가를 가져간다는 느낌이 드는 건 당연합니다. 공식 문서를 직접 확인했습니다.
💡 공식 개인정보 문서와 비교 분석 자료를 같이 놓고 보니, 인증 방식마다 데이터 처리 조건이 완전히 달랐습니다.
(출처: geminicli.com/docs/resources/tos-privacy/, Gemini Code Assist FAQs, developers.google.com/gemini-code-assist/resources/faqs)
기업 코드나 업무용 프로젝트를 다루는 경우라면 opt-out을 먼저 설정하는 게 맞습니다. 방법은 간단합니다.
# Gemini CLI 내에서
/settings
# → Usage Statistics → Off 설정단, Shipyard.build의 비교 분석에 따르면 무료 티어(구글 계정) 사용 시 기본값은 입출력 데이터 수집 ON 상태입니다. Claude Code(Anthropic)는 유료 플랜 기준으로 학습 데이터 사용을 하지 않으며, Vertex AI를 통한 Gemini CLI 역시 Google Cloud 정책상 학습 사용이 없습니다. (출처: shipyard.build, 2026.01.15)
Claude Code·Copilot CLI와 뭐가 다른가
코딩 에이전트 도구 3종을 핵심 지표로만 비교하면 이렇습니다. (출처: FreeAcademy.ai, 2026.02.15 / Shipyard.build, 2026.01.15)
컨텍스트 1M 토큰이 실제로 어느 정도냐면, 일반적인 중소 규모 프로젝트 전체 코드베이스를 한 번에 메모리에 올릴 수 있는 수준입니다. Claude Code(200K)보다 5배 큰 공간입니다. 대용량 모노레포 탐색에서 Gemini CLI가 유리한 이유가 여기 있습니다.
단, Reddit(r/GeminiCLI) 사용자들의 실제 후기를 종합하면 “복잡한 멀티스텝 디버깅에서 Claude Code는 스스로 방향을 재조정하는데 Gemini CLI는 막히면 그냥 사용자에게 넘기려 한다”는 공통된 평가가 반복됩니다. 이건 모델 차이이기도 하지만, 시스템 프롬프트 설계의 차이이기도 합니다.
실제로 쓸 만한 조건과 아닌 조건
Gemini CLI가 제값을 하는 상황과 그렇지 않은 상황을 솔직하게 정리하면 이렇습니다.
✅ 이런 상황이면 Gemini CLI가 맞습니다
- 예산이 없는 개인 개발자: 구글 계정 하나로 무료 1,000 req/day, Gemini 3 Pro 자동 라우팅까지
- 대형 모노레포 탐색: 1M 토큰 컨텍스트로 대규모 코드베이스 전체를 파악하는 작업
- Google Cloud / Firebase 환경: Cloud Run, BigQuery, Firebase 네이티브 확장 기본 탑재
- 도구 투명성이 필요한 팀: Apache 2.0 오픈소스라 내부 코드 감사, 커스터마이징 가능
- vi, git rebase 같은 인터랙티브 명령 필요 시: PTY(pseudo-terminal) 지원으로 Claude Code가 못 하는 작업 처리
❌ 이런 상황이면 다른 도구를 쓰는 게 낫습니다
- 기업 코드 + 무료 티어 조합: 기본값이 데이터 수집 ON, opt-out 안 하면 코드가 학습에 쓰일 수 있음
- 복잡한 멀티스텝 추론이 핵심인 작업: 논리 오류 가능성이 Claude Code 대비 높다는 실사용 평가가 지속적으로 나옴
- GitHub PR·이슈 중심 워크플로우: GitHub 네이티브 연동은 Copilot CLI가 확실히 우세
- API 키 무료로 Gemini 3 Pro를 쓰려는 경우: API 키 무료 = Gemini Flash 전용, 250 req/day 제한
- 오전에 크고 복잡한 작업을 몰아서 하는 경우: 작업 하나에 20~50 요청 소진 구조상 한도 초과 위험 높음
솔직한 총평: Gemini CLI는 “처음 써보는 터미널 AI 에이전트”로 시작하기에 손색없습니다. 단, 프로 레벨 업무 투입 전에 Plan 모드 동작 방식과 데이터 opt-out 설정은 반드시 확인해야 합니다. 무료니까 가볍게 쓰다 보면 정작 중요한 작업에서 한도 소진과 데이터 수집 두 가지를 동시에 맞을 수 있습니다.
Q&A 5가지
마치며
Gemini CLI는 2026년 3월 현재 AI 코딩 에이전트 중 가장 진입 장벽이 낮습니다. 구글 계정만 있으면 Gemini 3 Pro를 하루 1,000 요청 범위에서 무료로 쓸 수 있고, Plan 모드 추가로 계획-실행 이중 구조까지 갖췄습니다.
그런데 “무료”라는 라벨이 실제 사용 구조를 가립니다. 파일 하나 읽을 때마다 요청 1건이 나가고, 복잡한 작업 하나면 쉽게 20~50건이 사라집니다. 무료 티어 기본값이 데이터 수집 ON이라는 것도 업무용으로 쓸 때 반드시 체크해야 할 부분입니다.
Plan 모드의 자동 모델 라우팅 — 계획 단계에서 Gemini 3 Pro, 실행 단계에서 Flash로 자동 전환되는 구조 — 은 비용과 품질을 동시에 잡으려는 시도입니다. 이 부분은 써봤을 때 체감이 꽤 됩니다. 무료로 시작해서 한계를 직접 확인하고, 그 다음 단계를 결정하는 게 현실적입니다.
📎 본 포스팅 참고 자료
- Gemini CLI 공식 Plan 모드 문서 — geminicli.com/docs/cli/plan-mode/
- Gemini CLI 공식 요금 및 할당량 문서 — geminicli.com/docs/resources/quota-and-pricing/
- Gemini CLI 공식 약관·개인정보 문서 — geminicli.com/docs/resources/tos-privacy/
- Gemini CLI Gemini 3 모델 안내 — geminicli.com/docs/get-started/gemini-3/
- Claude Code vs Gemini CLI 비교 (Shipyard.build, 2026.01.15) — shipyard.build/blog/claude-code-vs-gemini-cli/
- Claude Code vs Gemini CLI vs Copilot CLI 비교 (FreeAcademy.ai, 2026.02.15) — freeacademy.ai
- 구글 개발자 블로그 3월 2주차 업데이트 (2026.03.13) — developers-kr.googleblog.com
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 지속적으로 업데이트되는 오픈소스 프로젝트이므로 요금 구조와 모델 할당량은 공식 문서에서 최신 정보를 직접 확인하시기 바랍니다.
댓글 남기기