gemini cli 모델 변경 — 3가지 방법과 우선순위
Gemini CLI에서 모델을 바꾸는 방법은 세 가지고, 서로 세는 순서가 정해져 있습니다. ① 대화 중에 바꾸려면 /model set pro, 이 설정을 다음에도 쓰려면 뒤에 --persist를 붙입니다. ② 이번 실행만 바꾸려면 gemini -m flash처럼 플래그를 줍니다. ③ 늘 같은 모델을 쓰려면 settings.json에 model.name을 적습니다. 셋이 겹치면 플래그 → 환경변수 GEMINI_MODEL → 설정 파일 → 기본값(auto) 순으로 이깁니다. 아래는 Gemini CLI 0.56.0 기준으로 하나씩 확인한 내용입니다.
1. 지금 무슨 모델을 쓰고 있나 — 기본값은 auto
아무것도 지정하지 않으면 모델 이름은 auto입니다. 특정 모델이 아니라 작업에 따라 알아서 고르는 설정이고, 공식 문서도 대부분의 경우 이 Auto를 권장합니다. 복잡한 추론에는 Pro, 빠른 응답에는 Flash 쪽으로 자동으로 기울게 하는 방식입니다.
이름 자리에는 gemini-2.5-pro 같은 전체 모델명 말고 짧은 별칭도 그대로 쓸 수 있습니다. 0.56.0 설치본에 들어 있는 별칭은 네 개입니다.
| 별칭 | 뜻 |
|---|---|
auto |
기본값. 작업에 맞는 모델을 알아서 고른다 |
pro |
추론·품질 쪽. 복잡한 디버깅·설계에 쓴다 |
flash |
속도 쪽. 짧고 단순한 요청에 쓴다 |
flash-lite |
가장 가벼운 쪽 |
2. 대화 중에 바꾸기 — /model
CLI를 켠 상태에서 /model만 치면 선택 창이 뜹니다. Auto (Gemini 3), Auto (Gemini 2.5), 그리고 특정 모델을 직접 고르는 Manual 중에서 고르는 방식입니다.
창을 거치지 않고 한 줄로 바꾸려면 set 하위 명령을 씁니다.
/model set pro
/model set gemini-2.5-flash여기서 많이 놓치는 게 하나 있습니다. 이렇게 바꾼 모델은 그 세션에서만 유효합니다. CLI를 껐다 켜면 원래대로 돌아옵니다. 다음에도 계속 그 모델로 시작하고 싶으면 --persist를 붙여야 합니다.
/model set pro --persist--persist가 하는 일은 홈 폴더의 사용자 설정 파일에 model.name을 써 넣는 것입니다. 0.56.0 소스에서 이 옵션은 setValue("User", "model.name", model)로 이어집니다. 즉 3번에서 설명하는 ~/.gemini/settings.json을 손으로 고치는 것과 결과가 같습니다. 프로젝트별로 다른 모델을 쓰고 싶다면 이 옵션 말고 프로젝트 설정 파일을 써야 합니다.
3. 늘 같은 모델로 시작하기 — settings.json의 model.name
설정 파일에 적어 두면 매번 지정할 필요가 없습니다. 위치는 두 곳을 기억하면 됩니다.
| 범위 | 경로 | 적용 대상 |
|---|---|---|
| 사용자 | ~/.gemini/settings.json |
내 계정의 모든 세션 |
| 프로젝트 | 프로젝트 루트의 .gemini/settings.json |
그 폴더에서 실행할 때만 (사용자 설정을 덮는다) |
내용은 이렇게 model 객체 안에 name으로 넣습니다. 옛 글에서 자주 보이는 최상위 "model": "..." 형태가 아닙니다.
{
"model": {
"name": "gemini-2.5-flash"
}
}회사 노트북과 개인 노트북에서 다른 모델을 쓰거나, 무거운 프로젝트에서만 Pro를 쓰고 싶을 때는 프로젝트 폴더 쪽 파일에 적으면 됩니다. 프로젝트 설정이 사용자 설정을 덮습니다.
4. 이번 실행만 바꾸기 — -m 플래그와 GEMINI_MODEL
설정을 건드리지 않고 딱 한 번만 다른 모델로 돌리고 싶을 때가 있습니다. 이때는 실행할 때 플래그를 줍니다. gemini --help에도 -m, --model로 나와 있습니다.
gemini -m flash
gemini --model gemini-2.5-pro스크립트나 CI에서 여러 명령을 같은 모델로 돌릴 때는 환경변수가 편합니다.
# macOS / Linux
export GEMINI_MODEL="gemini-2.5-flash"
# Windows PowerShell
$env:GEMINI_MODEL="gemini-2.5-flash"5. 셋이 겹치면 뭐가 이기나 — 우선순위
플래그도 주고 설정 파일에도 적어 놨다면 어느 쪽이 이길까요. 0.56.0의 모델 결정 코드는 이 한 줄로 정리됩니다.
const rawModel = argv.model || process.env["GEMINI_MODEL"] || settings.model?.name;왼쪽이 있으면 오른쪽은 보지도 않습니다. 표로 옮기면 이렇습니다.
| 순서 | 지정 방법 | 유효 범위 |
|---|---|---|
| 1 (가장 셈) | -m / --model |
그 실행 한 번 |
| 2 | GEMINI_MODEL 환경변수 |
그 셸(터미널) 세션 |
| 3 | settings.json의 model.name |
사용자 전체 또는 그 프로젝트 |
| 4 | 아무것도 없을 때 | 기본값 auto |
"설정 파일에 적었는데 안 바뀐다"는 대부분 여기서 갈립니다. 예전에 셸 프로필에 GEMINI_MODEL을 넣어 둔 걸 잊었거나, 실행 스크립트에 -m이 박혀 있는 경우입니다. 설정을 고치기 전에 echo $GEMINI_MODEL(PowerShell은 $env:GEMINI_MODEL)부터 확인해 보세요.
6. 바꿔도 안 바뀌는 것들
모델을 바꿨는데 사용 기록에는 다른 모델이 찍히는 경우가 있습니다. 이건 고장이 아닙니다.
- 서브에이전트는 따로 논다. 공식 문서는
/model명령과--model플래그가 서브에이전트가 쓰는 모델까지 바꾸지는 않는다고 못박고 있습니다. 그래서 모델 사용량 보고서에 지정하지 않은 모델이 같이 보일 수 있습니다. 자기 계정의 모델별 사용량이 궁금하다면 gemini cli 사용량 확인 쪽을 같이 보세요. - 권한이 없으면 조용히 내려간다. 프리뷰 모델 접근 권한이 없는 계정에서
pro나auto를 고르면, 0.56.0은 프리뷰 대신gemini-2.5-pro로 내려서 씁니다(flash계열도 마찬가지로 정식 모델 쪽으로 내려갑니다). 이름을 골랐다고 그 모델이 보장되는 건 아닙니다.
자주 묻는 것
Q. /model set과 설정 파일 중 뭘 써야 하나요?
지금 이 대화에서만 잠깐 바꾸는 거면 /model set, 앞으로도 계속 그 모델이면 --persist나 설정 파일입니다. 둘은 결국 같은 곳(사용자 설정의 model.name)에 저장되니 취향대로 고르면 됩니다.
Q. 모델 이름을 잘못 적으면 어떻게 되나요?
별칭이 아닌 이름은 그대로 모델명으로 넘어갑니다. 오타가 있으면 요청 단계에서 실패하니, 확실하지 않으면 /model 창에서 목록을 보고 고르는 편이 안전합니다.
Q. 프로젝트마다 다른 모델을 쓸 수 있나요?
됩니다. 프로젝트 루트에 .gemini/settings.json을 만들고 model.name을 적으면 그 폴더에서 실행할 때만 적용됩니다. 사용자 설정보다 프로젝트 설정이 우선입니다.
Q. 지금 설정이 어디서 온 건지 어떻게 아나요?
순서대로 지워 가며 확인하는 게 가장 빠릅니다. 실행 명령에 -m이 있는지, 셸에 GEMINI_MODEL이 떠 있는지, 그다음 프로젝트 .gemini/settings.json, 마지막으로 홈의 ~/.gemini/settings.json 순입니다.
마무리
정리하면 이렇습니다. 잠깐 바꾸는 건 /model set, 계속 쓰는 건 --persist나 settings.json의 model.name, 한 번만은 -m 플래그입니다. 겹칠 때는 플래그 → 환경변수 → 설정 파일 → auto 순으로 이기고, 서브에이전트와 권한 없는 프리뷰 모델은 이 지정을 그대로 따르지 않습니다.
CLI는 버전이 자주 오르니, 명령이나 설정 키가 이 글과 다르면 gemini --version으로 본인 버전을 확인하고 공식 문서를 한 번 열어 보세요.
📚 참고 출처 (2026년 9월 7일 확인 · 기준 Gemini CLI 0.56.0)
· Gemini CLI 공식 문서 — Gemini CLI model selection (/model command)
· Gemini CLI 공식 문서 — Commands reference
· Gemini CLI 공식 문서 — Configuration
· Google Developers Blog — Transitioning Gemini CLI to Antigravity CLI
COMMENTS