Gemini CLI 최신 버전
IT/AI
Gemini CLI Plan 모드, 무료 1,000회 다 쓸 수 있을까요?
2026년 3월 11일, Google이 Gemini CLI에 Plan 모드를 정식 추가했습니다. 코드 수정 없이 코드베이스를 분석하고 계획만 짜주는 Read-Only 모드인데, 막상 써보면 무료 쿼터 소진 속도가 예상과 다릅니다.
Plan 모드, 실제로 뭘 하는 기능인가요?
결론부터 말씀드리면, Plan 모드는 AI가 코드를 건드리지 않고 분석만 하는 상태입니다. 파일을 읽고, 패턴을 검색하고, 문서를 참조하되, 어떤 파일도 수정하지 않습니다. (출처: Google Developers Blog, 2026.03.11)
기존에 AI 코딩 도구를 써봤다면, “AI가 멋대로 파일을 바꿔버려서 롤백했다”는 경험이 한 번쯤 있을 겁니다. Plan 모드는 그 문제를 구조적으로 막는 장치입니다. 허용되는 도구가 read_file, grep_search, glob 등 읽기 전용으로 고정되고, 쓰기는 ~/.gemini/tmp/ 하위 plans 폴더의 .md 파일에만 가능합니다.
새로 추가된 ask_user 도구도 주목할 부분입니다. AI가 분석 도중 모호한 지점에서 멈추고 질문을 던집니다. “어떤 DB 마이그레이션 전략을 선호하시나요?”처럼 선택지를 제시하고 답변을 받아 계획에 반영합니다. 이 흐름이 끝나면 Markdown 파일로 실행 계획이 저장됩니다.
💡 공식 발표문과 실제 툴 제한 목록을 같이 놓고 보니, Plan 모드가 “안전한 탐색”이라기보다는 모델에게 강제로 쓰기 권한을 박탈하는 구조임을 알 수 있습니다. 설정으로 해제 가능하지만, 기본값은 항상 제한 상태입니다.
무료 1,000회인데, API 키로 쓰면 왜 250회일까요?
Gemini CLI의 “무료 1,000회”는 Google 계정으로 로그인한 경우에만 적용됩니다. API 키 방식으로 인증하면 하루 250회, 분당 10회 제한이 걸리고, 모델도 Flash 계열만 사용됩니다. (출처: Gemini CLI 공식 Quota 문서)
| 인증 방식 | 일일 요청 수 | 분당 요청 수 | 사용 가능 모델 |
|---|---|---|---|
| Google 계정 로그인 | 1,000회 | 60회 | Gemini 전 모델 (자동 선택) |
| Gemini API 키 (무료) | 250회 | 10회 | Flash 모델만 |
| Vertex AI Express | 가변 (90일 무료) | 가변 | 가변 |
이 차이가 중요한 이유는, 개발자들이 CI/CD 파이프라인이나 스크립트에서 Gemini CLI를 쓸 때 보통 API 키 방식을 선택하기 때문입니다. 그 경우 Plan 모드 자체가 Flash 모델 위에서 돌아가고, Pro 수준의 추론 품질은 기대할 수 없습니다.
Plan 모드 켜면 Pro 모델이 붙습니다 — 쿼터가 빨리 닳는 이유
Plan 모드에는 자동 모델 라우팅이 기본 활성화돼 있습니다. 계획(Planning) 단계에서는 Gemini 3.1 Pro가 자동으로 투입되고, 계획 승인 후 구현 단계로 넘어가면 Flash로 전환됩니다. (출처: Gemini CLI Plan Mode 공식 문서)
이게 왜 문제냐면, Plan 모드 한 세션에서 Ask-User 루프가 길어지거나 코드베이스 탐색 깊이가 깊어지면 Pro 모델 요청 수가 빠르게 올라갑니다. Google 계정 로그인 기준 1,000회가 Flash와 Pro 요청을 합산한 수치이기 때문에, Plan 모드를 적극적으로 쓰면 Flash 전용으로 쓸 때보다 체감 잔여 요청이 훨씬 빨리 줄어듭니다. 이 수치가 실생활에서 의미하는 바는, 하루 2~3회의 대규모 Plan 세션만으로 무료 쿼터 상당 부분이 소진될 수 있다는 겁니다.
💡 공식 문서의 모델 라우팅 설명과 실제 쿼터 구조를 교차해 보면, “무료이지만 Pro 추론을 쓴다”는 점이 오히려 무료 한도를 빠르게 소진하는 구조로 작동합니다. Plan 모드를 끄거나 "modelRouting": false로 설정해 Flash만 고정해 쓰는 게 쿼터 관리에는 유리합니다.
자동완성 기능이 Pro 쿼터를 먼저 씁니다
이건 공식 블로그에서 다루지 않은 부분인데, GitHub 공식 저장소 토론 스레드에서 보고된 문제입니다. Gemini CLI의 Prompt Completion(자동완성) 기능이 현재 선택된 채팅 모델과 동일한 모델을 사용합니다. Plan 모드에서 Gemini 3.1 Pro Preview 모델이 활성화된 상태라면, 프롬프트 입력창에 글자를 타이핑하는 것만으로도 Pro 모델 API 요청이 발생합니다. (출처: GitHub Discussions #17278)
실제로 이 문제를 겪은 사용자는 “단 하나의 프롬프트를 보내기도 전에 일일 요청 한도(RPD)를 모두 소진했다”고 보고했습니다. 이 수치가 의미하는 바는, Plan 모드 + Pro 모델 조합에서는 타이핑 행위 자체가 쿼터를 잠식할 수 있다는 점입니다.
⚠️ 현재 알려진 임시 해결책
Gemini CLI /settings에서 자동완성(Prompt Completion)을 비활성화하거나, 모델을 명시적으로 Flash로 고정하면 이 문제를 피할 수 있습니다. 공식 수정 여부는 확인 필요 상태입니다.
MCP 도구 연결, Plan 모드에서는 안 되는 게 있습니다
Plan 모드는 MCP 도구도 지원한다고 발표했지만, 읽기 전용 MCP 도구만 허용됩니다. 예를 들어 GitHub 이슈 읽기, PostgreSQL 스키마 조회 같은 건 가능합니다. 하지만 DB에서 실시간 로그를 조회하거나 외부 API로 현재 상태를 가져오는 작업은 기본 설정에서 차단됩니다. (출처: Gemini CLI Plan Mode 공식 문서 — Tool Restrictions)
Reddit 커뮤니티에서 실사용자들이 제기한 불만이 정확히 이 지점입니다. “계획을 짜는 데 있어서 DB 현재 상태나 API 응답을 참조할 수 없다면 계획의 반이 날아가는 것”이라는 지적이 있었고, 이는 Claude Code의 /plan 기능과 비교해 경쟁력이 약한 부분으로 꼽혔습니다.
단, 정책 엔진(Policy Engine)을 수동으로 설정하면 특정 MCP 도구를 Plan 모드에서 허용할 수 있습니다. ~/.gemini/policies/ 경로에 .toml 파일을 추가해 readOnlyHint: true인 도구를 일괄 허용하거나, 특정 도구명을 명시해 활성화하는 방식입니다. 기본 설정에서는 안 되지만, 수동 설정으로 확장이 가능하다는 점은 긍정적입니다.
Plan 모드를 실제로 쓸 만한 상황, 안 쓸 상황
써보니까 Plan 모드가 확실히 빛나는 상황이 있습니다. 생전 처음 보는 대형 코드베이스에서 “이 기능이 어디에 어떻게 구현돼 있지?”를 파악해야 할 때, 혹은 DB 마이그레이션처럼 실수하면 되돌리기 어려운 작업 전 설계 단계를 잡을 때입니다. 이 경우엔 AI가 파일을 건드리지 않으니 탐색을 맘껏 시킬 수 있습니다.
반면, 간단한 함수 하나 추가하거나 버그 하나 고치는 작업엔 Plan 모드가 오히려 느립니다. Ask-User 루프, 계획 파일 생성, 승인 과정이 단순 구현보다 긴 경우가 많습니다. 또한, 위에서 언급한 쿼터 소진 구조 때문에 하루 요청 수가 빡빡한 환경에서는 Plan 모드를 무분별하게 켜두는 것도 좋지 않습니다. 기본값으로 Plan 모드가 활성화돼 있다는 점에 주의가 필요합니다. 설치 후 아무 설정을 안 했다면 지금 이 순간에도 Plan 모드가 켜져 있는 상태일 수 있습니다.
💡 공식 문서에서 “기본값으로 모든 사용자에게 활성화”라고 명시하고 있는데, 이는 기존에 쓰던 방식과 동작이 달라졌을 수 있다는 의미입니다. Plan 모드 없이 바로 실행하던 워크플로우가 이제는 계획 단계를 먼저 거치게 됩니다. 불편하다면 /settings에서 Default Approval Mode를 Default나 Auto-Edit으로 바꾸면 됩니다.
Q&A
Q. Plan 모드는 어떻게 켜고 끄나요?
입력창에 /plan을 입력하거나, Shift+Tab으로 모드를 순환하거나, “start a plan for…”처럼 자연어로 요청하면 됩니다. 끄려면 같은 방식으로 다른 모드로 전환하거나, /settings에서 Plan을 Shift+Tab 순환에서 제외할 수 있습니다. (출처: Gemini CLI 공식 문서)
Q. 무료 플랜으로 Plan 모드를 써도 되나요?
Google 계정으로 로그인하면 하루 1,000회 범위 안에서 Plan 모드를 쓸 수 있습니다. 다만 Plan 모드 중 자동 모델 라우팅으로 Pro 모델이 투입되면 쿼터 소진이 빠릅니다. API 키 방식(무료)은 하루 250회, Flash만 지원되므로 Plan 모드의 추론 품질이 낮아집니다.
Q. Plan 모드에서 만들어진 계획 파일은 어디에 저장되나요?
기본적으로 ~/.gemini/tmp/<project>/<session-id>/plans/에 Markdown 파일로 저장됩니다. 세션은 30일 후 자동 삭제됩니다. 프로젝트 내부 디렉토리에 저장하고 싶다면 settings.json에서 경로를 커스텀할 수 있습니다. (출처: Gemini CLI 공식 문서)
Q. Plan 모드에서 Git 명령어를 실행할 수 있나요?
기본값에서는 불가합니다. 단, Policy Engine 설정 파일을 추가해 git status, git diff 같은 읽기 전용 Git 명령어를 Plan 모드에서 허용할 수 있습니다. 쓰기 작업(git commit, git push 등)은 Plan 모드 취지에 어긋나므로 허용하지 않는 게 권장됩니다.
Q. Conductor 확장이 Plan 모드와 어떻게 연결되나요?
Conductor는 Plan 모드를 활용하는 외부 확장 도구입니다. 복잡한 다단계 개발 프로젝트에서 “설계 → 확인 → 구현” 흐름을 자동화하고, 각 단계별 산출물을 프로젝트 내부에 저장합니다. 현재는 외부 확장이지만 Google이 Gemini CLI 내장 모드로 포함할 계획을 밝혔습니다.
마치며
Gemini CLI Plan 모드는 방향성 자체는 맞습니다. AI 코딩 도구가 “일단 코드 건드려보고 되면 OK”식이 아니라, 탐색과 설계를 먼저 하는 구조로 진화하고 있다는 신호입니다. 이게 핵심입니다.
다만 이 글에서 확인한 것처럼, “무료 1,000회”라는 숫자는 인증 방식과 모델 라우팅 조합에 따라 실제로는 훨씬 적게 느껴질 수 있습니다. Plan 모드를 적극적으로 쓰려면 Google 계정 로그인 방식을 쓰고, 자동완성과 Pro 모델 자동 전환 설정을 의식적으로 관리하는 게 좋습니다.
MCP 도구 제한, 자동완성 쿼터 소진 버그는 아직 개선 중인 부분입니다. 지금 당장 프로덕션 워크플로우에 넣기보다는, 대형 코드베이스 분석이나 설계 검토 용도로 조심스럽게 쓰기 시작하는 게 적절합니다.
본 포스팅 참고 자료
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 업데이트 주기가 빠르므로 최신 정보는 공식 문서를 통해 확인하시기 바랍니다. | 2026.03.18 작성
댓글 남기기