Plan 모드가 기본 켜진다고 해서 Pro 모델을 공짜로 쓰는 건 아닙니다. 무료 API 키 사용자에게는 Flash만 라우팅됩니다. 공식 문서와 요금표를 직접 교차해서 확인한 결과입니다.
Pro 모델 2026.03.25부터 유료 전환
Plan 모드 출시일: 2026.03.11
Plan 모드가 뭔지부터 — 핵심 3줄
공식 발표 문구를 그대로 옮기면 이렇습니다. “Plan mode is a read-only mode that restricts Gemini CLI to a subset of its tools.” 계획이 확정되면 그때 실행 단계로 전환하고, 실행 단계에서는 자동으로 Flash 모델로 라우팅이 바뀝니다. Pro는 계획 단계에서만, Flash는 구현 단계에서 씁니다.
여기서부터가 핵심입니다. “계획 단계에서 Pro를 쓴다”는 조건이 붙는데, 이게 모든 사용자에게 적용되는 게 아닙니다. 아래 섹션에서 바로 짚겠습니다.
Plan 모드인데 왜 Pro가 안 뜨는가
💡 공식 요금표와 Plan 모드 발표문을 같이 놓고 보니 이런 차이가 보였습니다. Plan 모드는 “Pro를 씁니다”가 아니라 “auto 모델 설정일 때 Pro로 라우팅합니다”입니다.
공식 문서에는 이렇게 나옵니다. “When using an auto model, Gemini CLI automatically optimizes model routing based on the current phase.” (출처: geminicli.com/docs/cli/plan-mode/, 2026.03) 핵심은 ‘auto model 설정일 때만’입니다.
그런데 무료 API 키(Unpaid)를 쓰면 어떻게 될까요? 공식 요금표에 직접 나와 있습니다. “Model requests to Flash model only.” (출처: geminicli.com/docs/resources/quota-and-pricing/, 2026.03) 무료 API 키 사용자는 Flash 모델만 접근 가능하고, 하루 최대 250 요청이 한도입니다.
| 인증 방식 | Plan 모드 Pro 라우팅 | 하루 요청 한도 | 비용 |
|---|---|---|---|
| 구글 계정 로그인 (무료) | ✅ 가능 | 1,000 req | 무료 |
| Gemini API 키 (무료) | ❌ Flash만 | 250 req | 무료 |
| Google AI Pro | ✅ 가능 | 1,500 req | 약 $20/월 |
| Google AI Ultra | ✅ 가능 | 2,000 req | 약 $250/월 |
표 출처: geminicli.com/docs/resources/quota-and-pricing/ (2026.03)
정리하면 이렇습니다. API 키로 세팅한 사람이 Plan 모드를 켜도, 계획 단계에서 Pro가 아닌 Flash가 씁니다. Pro가 복잡한 아키텍처 결정에 쓰인다는 Plan 모드의 핵심 장점이 그대로 증발합니다. 무료로 API 키 세팅을 권장하는 튜토리얼이 많은데, 이 맥락을 빠뜨리면 기대와 현실이 달라집니다.
한편, 2026년 3월 25일 이후 GitHub Discussions에 올라온 공지에 따르면, 무료 티어에서 Pro 모델 접근 자체가 제한됩니다. “Starting March 25, 2026, Gemini Pro models will only be accessible via paid subscriptions.” (출처: github.com/google-gemini/gemini-cli/discussions/22970, 2026.03.29) 이 제한은 Gemini Code Assist 무료 계정에도 영향을 줍니다.
실제로 Plan 모드를 켜는 3가지 방법
공식 문서에 나온 진입 방법은 세 가지입니다. (출처: geminicli.com/docs/cli/plan-mode/, 2026.03)
키보드 단축키
Shift+Tab으로 모드를 순환합니다. Default → Auto-Edit → Plan 순서로 돌아갑니다. AI가 처리 중이거나 확인 다이얼로그가 떠 있을 때는 Plan이 순환에서 빠집니다.
슬래시 커맨드
입력창에 /plan을 치면 바로 진입합니다. CLI 시작 시부터 적용하려면 gemini --approval-mode=plan을 씁니다.
자연어 요청
“start a plan for…”라고 입력하면 AI가 enter_plan_mode 도구를 자동 호출합니다. 단, YOLO 모드 상태일 때는 이 방법이 막힙니다.
기본값으로 고정하고 싶다면 /settings → Default Approval Mode → Plan으로 변경하면 됩니다. 반대로 Plan 모드를 완전히 끄고 싶으면 같은 메뉴에서 “Plan”을 검색해 토글을 끄면 됩니다. 이렇게 하면 Shift+Tab 순환에서도 빠지고, enter/exit_plan_mode 도구 자체가 비활성화됩니다.
Plan 모드가 막는 것과 허용하는 것
“읽기 전용”이라고 하는데, 구체적으로 어디까지 막히는지 모르면 세션 중에 답답할 수 있습니다. 공식 문서에 허용 도구 목록이 명확히 나와 있습니다.
✅ 허용
read_file,list_directory,glob— 파일 읽기grep_search,google_web_search— 검색codebase_investigator,cli_help— 서브에이전트ask_user— 사용자에게 질문- 읽기 전용 MCP 도구 (github_read_issue, postgres_read_schema 등)
write_file,replace— 플랜 .md 파일만 허용save_memory
❌ 차단
- 소스 코드 파일 직접 수정
- 쉘 커맨드 실행 (
run_shell_command) - npm, pip, 패키지 설치
- 쓰기 MCP 도구
- YOLO 모드 동시 사용 시
enter_plan_mode자체 차단
커스텀 정책 파일(~/.gemini/policies/ 디렉터리)을 만들면 일부 제한을 완화할 수 있습니다. 예를 들어 git status나 git diff는 Plan 모드에서도 실행하도록 정책을 추가하는 식입니다. (출처: geminicli.com/docs/cli/plan-mode/#custom-policies, 2026.03) 단, 이 설정은 Tier 2 정책으로, 내장 Tier 1보다 우선순위는 낮습니다.
플랜 파일은 30일 뒤 사라집니다
💡 Plan 모드로 만든 설계 문서를 팀 프로젝트에 남기려고 했는데 30일 후에 날아간다는 걸 공식 문서에서 발견했습니다. 기본 저장 경로가 프로젝트 폴더 밖이라는 것도 같이 보입니다.
Plan 모드가 생성하는 플랜 파일의 기본 저장 위치는 프로젝트 폴더가 아닙니다. ~/.gemini/tmp/<project>/<session-id>/plans/라는 임시 디렉터리입니다. (출처: geminicli.com/docs/cli/plan-mode/, 2026.03) 세션이 종료되고 30일이 지나면 이 파일은 자동으로 삭제됩니다.
설계 이력을 프로젝트 안에 남기고 싶다면 settings.json에 커스텀 경로를 직접 설정해야 합니다.
{
"general": {
"plan": {
"directory": ".gemini/plans"
}
}
}
단, 커스텀 경로는 프로젝트 루트 안에만 지정할 수 있습니다. 프로젝트 외부 경로를 설정해도 Gemini CLI가 허용하지 않습니다. 또한 커스텀 경로를 쓸 경우 해당 위치에 write_file을 허용하는 별도 정책 파일도 추가해야 합니다. 이 설정을 빠뜨리면 Plan 모드에서 해당 경로에 쓰기가 차단되고 플랜 파일이 생성되지 않습니다.
커스텀 경로로 저장된 파일은 자동 삭제 대상에서 제외됩니다. 그러나 수동으로 관리해야 하고, 세션 삭제 명령(gemini --delete-session)도 이 파일에는 영향을 주지 않습니다.
Claude Code Plan 모드와 뭐가 다른가
Claude Code도 Plan 모드가 있습니다. 사용법은 Gemini CLI와 거의 같습니다. Shift+Tab으로 순환하거나 /plan으로 진입하고, 플랜을 확정하면 실행으로 넘어갑니다. 겉보기엔 비슷하지만 실제 흐름에서 차이가 납니다.
| 항목 | Gemini CLI | Claude Code |
|---|---|---|
| Plan 기본값 | 기본 ON | 수동 진입 |
| Plan 중 사용 모델 | Gemini 3.1 Pro (유료 계정) | Haiku Explore Subagent |
| 플랜 파일 편집 | Ctrl+X → 외부 에디터 | Ctrl+G → 외부 에디터 |
| 무료 사용 가능 | ✅ (구글 계정 로그인 시) | ❌ (최소 $20/월) |
| 동일 작업 토큰 사용량 | 약 432K 입력 토큰 | 약 261K 입력 토큰 |
| 오픈소스 | ✅ Apache 2.0 | ❌ 독점 |
출처: datacamp.com/blog/gemini-cli-vs-claude-code (2026.03.26)
토큰 사용량 차이가 의미하는 건 이렇습니다. Gemini CLI가 같은 작업에 1.65배 더 많은 토큰을 씁니다. 무료 쿼터가 빠르게 소진된다는 뜻입니다. Plan 모드를 쓰면서 코드베이스를 탐색하면 Pro 모델로 라우팅된 쿼리가 쌓이는데, 이게 하루 1,000 req 한도에 모두 카운트됩니다.
Q&A 5가지
Q1. Plan 모드를 켜면 항상 Gemini 3.1 Pro가 사용되나요?
아닙니다. “auto model” 설정에서만 Plan 단계에 Pro, 실행 단계에 Flash로 자동 라우팅됩니다. API 키 무료 티어는 어떤 단계에서도 Flash 모델만 씁니다. 구글 계정으로 로그인한 무료 사용자는 Pro 접근이 가능하지만, 2026년 3월 25일 이후 무료 Pro 접근이 유료 전환됐습니다. (출처: github.com/google-gemini/gemini-cli/discussions/22970)
Q2. Plan 모드에서 만든 플랜 파일을 팀원과 공유하려면 어떻게 해야 하나요?
기본 경로(~/.gemini/tmp/)에 저장되면 팀 공유가 어렵습니다. settings.json에서 "plan": { "directory": ".gemini/plans" }처럼 프로젝트 루트 내부 경로로 변경하고, 이 경로에 쓰기를 허용하는 커스텀 정책 파일도 함께 추가해야 합니다. 이 파일을 git에 커밋하면 팀 공유가 가능합니다.
Q3. CI/CD 파이프라인에서 Plan 모드를 쓸 수 있나요?
씁니다. 비인터랙티브 환경에서는 enter/exit_plan_mode 도구가 사용자 확인 없이 자동으로 승인됩니다. 플랜이 확정되면 실행 단계에서 YOLO 모드로 자동 전환되어 중간 승인 없이 코드를 적용합니다. gemini --approval-mode plan -p "..." 형태로 사용합니다.
Q4. Plan 모드에서 git 명령어는 왜 안 되나요?
기본적으로 run_shell_command 자체가 차단되어 있어 git도 막힙니다. 단, 커스텀 정책 파일에 git status와 git diff를 허용하는 규칙을 추가하면 Plan 모드 내에서도 사용할 수 있습니다. git push, git commit 등 쓰기 성격의 git 명령은 읽기 전용 원칙에 어긋나므로 허용하지 않는 것이 안전합니다.
Q5. Plan 모드를 완전히 끄고 싶으면 어떻게 하나요?
/settings 명령을 입력하고 “Plan”을 검색한 뒤 토글을 끄면 됩니다. 이렇게 하면 Shift+Tab 순환에서 Plan이 제거되고, enter_plan_mode와 exit_plan_mode 도구 자체가 비활성화됩니다. Plan 모드를 쓰고 싶지 않은데 실수로 진입하는 문제를 원천 차단하는 방법입니다.
마치며
그런데 “기본 켜졌다”는 말에서 멈추면 안 됩니다. Pro 모델이 붙는 건 특정 인증 방식에서만이고, 플랜 파일은 30일이면 사라지며, 동일 작업에 Claude Code보다 토큰을 더 씁니다. 이 세 가지를 모르고 쓰면 기대하던 것과 다른 경험을 합니다.
구글 계정 로그인 방식이 지금 시점에서 가장 쓸 만한 무료 조합입니다. API 키 방식은 Flash 전용에 250 req 한도라 Plan 모드의 실질적 효과가 반감됩니다. 유료로 갈 생각이라면 Google AI Pro(약 $20/월)부터 시작해 하루 1,500 req와 Pro 모델 접근을 확보하는 게 현실적입니다.
본 포스팅 참고 자료
- Gemini CLI Plan Mode 공식 문서 — geminicli.com/docs/cli/plan-mode/
- Plan Mode 출시 공식 블로그 (2026.03.11) — developers.googleblog.com
- Gemini CLI 요금 및 할당량 공식 문서 — geminicli.com/docs/resources/quota-and-pricing/
- 서비스 업데이트 공지 (무료 Pro 제한, 2026.03.25) — github.com/google-gemini/gemini-cli/discussions/22970
- Gemini CLI vs. Claude Code 비교 (2026.03.26) — datacamp.com
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 빠르게 업데이트되는 도구로, 요금 구조와 모델 접근 정책이 사전 공지 없이 바뀔 수 있습니다. 중요한 결정 전에 공식 문서와 GitHub Discussions를 직접 확인하는 것을 권장합니다.
댓글 남기기