Google Gemini CLI 마스터 가이드

설치와 로그인

AI가 처음이라면, 터미널부터 손대지 마세요. 가장 쉬운 길은 브라우저(크롬·사파리·엣지)를 열어 주소창에 gemini.google.com 을 치고, 구글 계정으로 로그인만 하는 것입니다. 깔 것도, 명령어도 없습니다. 거기서 한국어로 '말'을 걸어 보며 'AI한테 시킨다'는 감을 먼저 잡으세요.

이 글이 다루는 Gemini CLI는 그다음 단계입니다. CLI는 웹사이트가 아니라 '터미널(검은 명령어 창)'에서 도는 도구라, 카톡처럼 누르는 전용 앱도, Claude의 'Code 탭' 같은 버튼식 화면도 없습니다. 그래서 여기서는 보여드릴 앱 스크린샷이 없고, 글과 순서로만 정직하게 설명합니다. 터미널이 처음이라면 맨 위 '왕초보 시작하기' 배너(/guides/start)부터 보고, '터미널을 쓸 줄 알게 된 다음' 이 글로 돌아오는 걸 권합니다.

터미널이 익숙해졌다는 전제에서, 로그인에는 중요한 변화가 있습니다. 한때는 '구글 계정으로 로그인'만 하면 넉넉한 무료 한도를 줬지만, 2026년 6월 그 개인 무료 티어가 종료됐습니다. 구글은 후속작 Antigravity CLI로의 이전을 안내하고 있고요. 그래서 지금 Gemini CLI를 붙이는 길은 사실상 키 기반 세 가지입니다.

셋은 이렇습니다. 첫째, Gemini API 키 — AI Studio(aistudio.google.com/apikey)에서 발급해 환경 변수 GEMINI_API_KEY로 설정합니다. 둘째, Vertex AI — GOOGLE_API_KEY와 함께 GOOGLE_GENAI_USE_VERTEXAI=true 를 두는 구글 클라우드 빌링 경로입니다. 셋째, Code Assist Standard·Enterprise 유료 좌석입니다. 세션 안에서는 /auth 로 인증 방식을 전환합니다.

주의 두 가지. 무료 OAuth가 사라졌으니 예전 글들의 '구글 로그인만 하면 공짜'는 더는 맞지 않습니다. 그리고 2026년 6월부터 Gemini API는 '제한 없는 키'를 거부하기 시작해, 새로 만들 때 사용처가 제한된 키로 발급해야 합니다. 무료로 쓸 수 있는 범위는 빠르게 바뀌니, 발급·결제 전 공식 문서를 한 번 더 확인하세요.

(고급 · 나중에) 터미널에 직접 설치하는 방법입니다. 지금 당장 몰라도 됩니다. Gemini CLI는 오픈소스라 설치 경로가 여럿입니다 — npm 'npm install -g @google/gemini-cli'(Node 20+), 설치 없이 한 번만 써보려면 'npx @google/gemini-cli', macOS·리눅스는 Homebrew 'brew install gemini-cli'(Node까지 알아서 처리)도 됩니다. 'npm·brew' 같은 말이 낯설다면, 그건 위에서 권한 웹 맛보기 → '왕초보 시작하기' 순서를 먼저 밟으라는 신호입니다.

첫 세션, 무엇을 어떻게 시키나

폴더에서 gemini 를 켜면 그 디렉터리에 묶인 대화형 에이전트가 뜹니다. 여기서부터는 '말'로 시작합니다. "이 프로젝트 구조를 설명해줘" 같은 평범한 요청이면 충분합니다. 특정 파일이나 폴더를 짚어 주고 싶으면 @ 를 씁니다 — '@src/ 이 폴더의 역할을 정리해줘'처럼요. @는 git 무시 규칙을 존중해 불필요한 파일은 빼고 읽습니다.

셸 명령을 직접 돌리고 싶으면 줄 맨 앞에 ! 를 붙입니다. 파일 읽기·쓰기·편집, 셸 실행, 웹 가져오기, 구글 검색 그라운딩 같은 내장 도구는 /tools 로 무엇이 있는지 확인할 수 있습니다. 도구가 실제로 어떤 일을 할 수 있는지를 알면 시킬 거리가 보입니다.

Gemini는 기본적으로 도구를 실행하기 전에 승인을 묻습니다. 흐름을 빠르게 굴리고 싶을 때는 자동 승인(YOLO) 모드로 올릴 수 있지만, 그만큼 사람의 확인이 빠지므로 익숙한 작업에만 쓰는 게 안전합니다(2장). 대화 없이 한 번에 돌리려면 'gemini -p "할 일"', 결과를 기계가 받게 하려면 --output-format json 을 씁니다.

첫 세션에서 외울 건 셋뿐입니다 — 막히면 /help, 맥락은 /memory(GEMINI.md), 프로젝트를 처음 열었으면 /init. GEMINI.md 한 장을 깔아 두면 다음 세션부터 같은 설명을 반복하지 않습니다(1장).

어떤 경로로 붙일까

무료 OAuth가 빠진 지금, 선택은 '어떤 키로 붙느냐'입니다. 세 경로 모두 장단이 있고, 금액·한도는 자주 바뀌니 숫자는 근사치로만 받아들이세요.

AI Studio API 키가 가장 간단합니다. 사용량 기반이고 일부 모델에는 무료 한도가 있다고 안내되지만, 그 한도가 Gemini CLI에서 그대로 통하는지는 시점에 따라 달라 직접 확인이 필요합니다. 혼자 가볍게 쓰거나 실험할 때 어울립니다.

Vertex AI는 구글 클라우드 빌링에 붙는 엔터프라이즈 경로로, 조직 단위 할당량과 보안 정책을 따릅니다. Code Assist Standard·Enterprise는 좌석제 유료로 하루 요청 한도가 커서 개발팀에 맞습니다. 둘 다 '회사에서 거버넌스를 갖춰 쓰는' 쪽에 가깝습니다.

고르는 기준은 단순합니다. 혼자·실험이면 AI Studio 키, 회사 클라우드에 통합하면 Vertex, 팀 좌석으로 한도와 관리가 필요하면 Code Assist. 무엇을 고르든 4장의 /stats·/compress 로 토큰을 아끼는 습관이 결국 비용을 지킵니다.

GEMINI.md, 세 층으로 쌓는 지침

GEMINI.md는 Gemini가 모든 프롬프트와 함께 읽는 지침 파일입니다. 빌드 명령, 코딩 규칙, 금지사항을 적어두면 매 대화에 자동으로 실립니다. 사람으로 치면 '신입에게 매번 처음부터 설명하지 않도록 정리해 둔 업무 매뉴얼'에 해당합니다.

왜 이게 중요할까요. 터미널 AI에 매번 같은 맥락을 손으로 붙여넣는 일은 생각보다 시간을 많이 잡아먹고, 더 큰 문제는 빠뜨리는 것입니다. '우리는 yarn이 아니라 pnpm을 쓴다', '커밋 메시지는 한국어로', '테스트는 vitest로'를 깜빡하면 Gemini는 그럴듯하지만 우리 규칙과 어긋난 결과를 냅니다. GEMINI.md는 그 맥락을 한 번 적어 영구히 거는 자리입니다.

핵심은 한 곳이 아니라 세 곳에 둘 수 있다는 점입니다. 전역은 ~/.gemini/GEMINI.md 입니다. 어느 프로젝트에서나 따르길 바라는 나만의 습관 — 한국어로 답하기, 설명은 짧게 — 을 여기 둡니다. 프로젝트는 ./GEMINI.md 로, 그 저장소의 빌드·테스트·아키텍처 규칙을 담습니다. 하위는 ./src/GEMINI.md 처럼 특정 폴더 안에 두어, 그 디렉터리에서 일할 때만 더해지는 세부 규칙을 적습니다.

세 층은 덮어쓰기가 아니라 연결입니다. Gemini는 위치에 맞는 파일들을 모아 하나의 계층 메모리로 읽습니다. 그래서 전역에는 큰 원칙을, 프로젝트에는 그 저장소의 규칙을, 하위에는 모듈별 디테일을 나눠 담을 수 있습니다. 흔한 실수는 모든 걸 전역 한 파일에 몰아넣는 것입니다. 그러면 프로젝트마다 안 맞는 규칙이 섞여 들어가 오히려 노이즈가 됩니다 — 층을 나누는 게 핵심입니다.

/init 으로 GEMINI.md를 자동 생성하기

맨손으로 GEMINI.md를 쓰는 것보다, 코드베이스를 한 번 훑게 한 뒤 다듬는 편이 빠릅니다. 프로젝트 폴더에서 /init 을 치면 Gemini가 구조를 분석해 GEMINI.md 초안을 만들어 줍니다. 디렉터리 구성, 주요 스크립트, 사용 중인 프레임워크를 스스로 읽고 정리하므로, 백지에서 시작하는 부담이 사라집니다.

왜 자동 생성을 권할까요. 사람이 직접 적으면 '당연해서 안 적는' 항목이 꼭 빠집니다. 정작 AI에게는 그 당연한 게 안 당연하죠. /init 은 외부 관찰자의 눈으로 프로젝트를 한 바퀴 훑어 주기 때문에, 내가 놓친 빌드 경로나 테스트 명령을 잡아내는 출발점이 됩니다.

다만 생성된 초안은 출발점일 뿐입니다. Gemini가 잘못 추측한 부분을 지우고, 빌드 명령과 '하지 말 것' 한두 줄만 더해도 다음 세션의 품질이 눈에 띄게 달라집니다. 특히 '절대 하지 말 것'(예: node_modules 수정 금지, main 직접 푸시 금지)은 자동 생성이 잘 못 잡는 영역이라 손으로 보강하는 값어치가 큽니다.

초안을 다듬을 때는 길게 쓰려는 욕심을 버리세요. GEMINI.md는 매 프롬프트에 함께 실리므로, 장황하면 그만큼 컨텍스트를 먹습니다. '짧고 단정한 규칙 목록'이 '문단으로 풀어쓴 설명'보다 거의 항상 낫습니다.

/memory 로 무엇이 읽혔는지 확인하기

세 층을 쓰다 보면 '지금 Gemini가 어떤 지침을 들고 있나'가 헷갈립니다. /memory 는 현재 로드된 계층 메모리를 보여주고 관리하게 해줍니다. 의도한 GEMINI.md가 실제로 실렸는지, 어디 것이 빠졌는지 여기서 확인합니다.

이게 왜 필요한가 하면, 계층 메모리는 '어느 폴더에서 Gemini를 실행했는지'에 따라 읽히는 파일이 달라지기 때문입니다. 같은 저장소라도 루트에서 띄울 때와 하위 폴더에서 띄울 때 잡히는 GEMINI.md가 다를 수 있습니다. 동작이 기대와 다르면 모델을 의심하기 전에 '무엇이 읽혔나'부터 보는 게 순서입니다.

지침을 고쳤는데 동작이 안 바뀌는 것 같으면, 먼저 /memory 로 어느 파일이 읽혔는지부터 봅니다. 대개는 파일을 엉뚱한 위치에 두었거나, 새로 추가한 파일이 아직 안 잡힌 경우입니다. 파일을 새로 만들거나 위치를 옮겼다면 /memory 로 갱신 상태를 다시 확인하세요.

운영 팁 하나. GEMINI.md를 고친 직후엔 습관적으로 /memory 를 한 번 확인하는 루틴을 들이면, '분명 적었는데 왜 안 듣지' 류의 시간 낭비가 크게 줄어듭니다. 메모리는 적는 일 못지않게 '제대로 실렸는지 검증하는 일'이 중요합니다.

Agent Skills, 필요할 때만 펼쳐지는 능력

Agent Skills는 SKILL.md 파일로 정의하는, 특정 작업을 위한 능력 묶음입니다. 예를 들면 '릴리스 노트 쓰는 법', '우리 회사 API 호출 규칙' 같은 절차를 한 스킬로 정리해 둡니다. GEMINI.md가 '항상 적용되는 상시 규칙'이라면, 스킬은 '특정 작업이 올 때만 꺼내 쓰는 절차서'입니다.

핵심 설계는 '점진적 공개(progressive disclosure)'입니다. Gemini는 평소엔 각 스킬의 메타데이터(이름·설명)만 가볍게 들고 있다가, 그 스킬이 필요한 상황이 오면 비로소 SKILL.md의 상세 내용을 읽어 들입니다. 덕분에 스킬을 수십 개 깔아도 매 대화의 컨텍스트가 무거워지지 않습니다. 모든 매뉴얼을 책상에 펼쳐두는 게 아니라, 제목만 보고 필요한 한 권만 꺼내는 방식입니다.

그래서 스킬을 잘 쓰는 비결은 '설명(메타데이터)을 정확히 쓰는 것'에 있습니다. Gemini는 그 설명을 보고 '지금 이 스킬을 펼칠지' 판단하므로, 언제 쓰는 스킬인지가 한 줄로 분명해야 제때 활성화됩니다. 모호한 설명은 필요할 때 안 펼쳐지거나, 엉뚱할 때 끼어드는 원인이 됩니다.

스킬은 세 스코프에 둘 수 있습니다. Extension에 포함되어 배포되거나, 사용자 스코프(~/.gemini/skills/)에 두어 내 모든 프로젝트에서 쓰거나, 워크스페이스 스코프(.gemini/skills/)에 두어 그 저장소에서만 쓰는 식입니다. '나만 쓰는 습관'은 사용자 스코프, '이 저장소의 규칙'은 워크스페이스 스코프, '팀에 배포할 능력'은 Extension에 담는다 — 이 매칭만 익혀도 절반은 됩니다.

Extensions, 도구·스킬·명령을 묶음째

Extensions는 도구·스킬·명령을 하나로 묶어 설치하는 단위입니다. 스킬이 '능력 한 조각'이라면, 확장은 그 조각들에 MCP 도구와 커스텀 명령까지 더한 '패키지'에 가깝습니다. 새 노트북을 받았을 때 앱 하나하나 까는 대신 설정 묶음을 통째로 복원하는 그림을 떠올리면 됩니다.

확장은 install / enable / disable 로 관리합니다. 새 도구 묶음을 들였다가, 지금 안 쓰는 건 disable 로 잠시 꺼두고, 필요할 때 다시 enable 합니다. /extensions 로 설치된 확장 목록과 상태를 확인합니다. 삭제까지 가지 않고 '잠깐 끄기'가 가능하다는 게 핵심인데, 설정은 그대로 둔 채 영향만 멈출 수 있어서입니다.

확장을 끄고 켜는 습관은 컨텍스트 위생에 좋습니다. 안 쓰는 도구가 많을수록 Gemini가 고려할 선택지가 늘어 판단이 흐려지므로, 지금 작업에 필요한 확장만 켜두는 편이 결과가 깔끔합니다. 도구가 20개 떠 있는데 그중 2개만 쓰는 상황이면, 나머지 18개는 잘못된 도구 선택의 후보로만 남습니다.

스킬과 확장을 헷갈리지 않는 기준을 한 번 더 못 박아 둡시다. 스킬은 '무엇을 어떻게 하는지(절차)'를 더하고, 확장은 '무엇을 할 수 있는지(능력·도구)'를 더합니다. 같은 확장 안에 스킬이 들어 있을 수 있으므로 둘은 배타적이지 않지만, '내가 배포·설치 단위로 다루는 건 확장, 그 안에서 펼쳐지는 절차는 스킬'이라고 잡으면 정리됩니다.

커스텀 명령, .toml 로 만드는 나만의 /명령

자주 쓰는 긴 프롬프트는 매번 타이핑하는 대신 커스텀 명령으로 박제할 수 있습니다. .toml 파일로 정의하면 /명령 형태로 호출됩니다. /commands 로 사용 가능한 커스텀 명령을 관리합니다.

예를 들어 'PR 설명을 우리 팀 템플릿대로 써줘' 같은 반복 지시를 .toml에 한 번 적어두면, 다음부터는 짧은 슬래시 한 줄로 같은 작업을 부릅니다. 매번 같은 문단을 복사해 오는 수고가 사라지고, 더 중요하게는 '사람마다 조금씩 다르게 입력하는' 편차가 없어집니다 — 같은 명령은 늘 같은 지시를 보냅니다.

스킬과 커스텀 명령의 차이도 짚어둘 만합니다. 스킬이 '상황을 보고 Gemini가 알아서 펼치는' 자동 능력이라면, 커스텀 명령은 '내가 직접 슬래시로 부르는' 수동 단축 명령입니다. 자동으로 끼어들면 곤란한 작업, 정확한 타이밍에 내가 직접 트리거하고 싶은 작업은 커스텀 명령이 더 잘 맞습니다.

운영상 좋은 출발점은 '같은 프롬프트를 세 번 친 순간'입니다. 그때가 .toml로 옮길 신호입니다. 처음부터 모든 걸 명령으로 만들려 하면 관리할 명령만 늘어나니, 반복이 확인된 것부터 박제하는 편이 깔끔합니다.

Plan Mode, 손대기 전에 계획부터

큰 변경일수록 곧장 실행시키면 불안합니다. /plan 으로 들어가는 Plan Mode는 읽기 전용입니다. Gemini가 코드를 분석하고 무엇을 어떻게 바꿀지 계획만 세울 뿐, 파일을 고치지는 않습니다. '말로만 먼저 보여줘'를 보장하는 모드라고 보면 됩니다.

왜 읽기 전용이 따로 필요할까요. AI 에이전트의 가장 큰 리스크는 '의도는 맞지만 범위를 잘못 잡은' 변경입니다. 다섯 파일만 고치면 될 일을 스무 파일 건드리거나, 엉뚱한 모듈까지 손대는 식이죠. 계획을 먼저 받으면 실행 전에 그 범위를 눈으로 확인하고 잘라낼 수 있습니다.

계획을 받아 검토한 뒤에야 실제 변경을 승인합니다. '먼저 계획 → 검토 → 실행' 순서는 되돌릴 수 없는 실수를 줄이는 가장 값싼 보험입니다. 특히 여러 파일을 건드리는 리팩터링, 마이그레이션, 대량 이름 변경처럼 한 번 어긋나면 수습이 오래 걸리는 작업에서 효과가 큽니다.

실무에서는 Plan Mode를 '협상 테이블'처럼 씁니다. 받은 계획에서 '이 파일은 건드리지 마', '이 단계는 빼고' 같은 조건을 붙여 다듬은 뒤 실행으로 넘기면, 처음부터 정확한 범위로 움직이게 됩니다. 계획 단계의 1~2분이 실행 후 롤백의 30분을 아낍니다.

권한과 정책, 어디까지 허용할지

Gemini가 도구를 쓰고 파일을 고칠 때마다 매번 묻는 게 안전하지만, 반복되면 피곤합니다. /permissions 로 무엇을 허용·거부할지 정리하고, /policies 로 동작 정책을 확인·관리합니다. 권한은 '이 동작은 물어보지 말고 해도 돼'와 '이건 절대 하지 마'의 경계를 미리 그어두는 일입니다.

여기서 균형이 중요합니다. 너무 좁게 잡으면 매 단계 확인하느라 흐름이 끊기고, 너무 넓게 잡으면 위험한 동작까지 무사통과됩니다. 권장 출발점은 '읽기·검색처럼 되돌릴 수 있는 동작은 허용, 삭제·푸시·외부 호출처럼 영향이 큰 동작은 확인 유지'입니다.

자동 승인은 강력하지만 위험합니다. 단축키 Ctrl+Y 로 켜는 YOLO 모드는 확인 절차를 건너뛰고 모든 동작을 자동 승인합니다. 신뢰할 수 있는 작업·격리된 환경에서만 켜고, 끝나면 다시 끄는 습관을 들이세요. /privacy 로는 개인정보 관련 설정을 확인합니다.

정책과 권한을 나눠 생각하면 운영이 쉬워집니다. 권한이 '개별 동작의 허용/거부 목록'이라면, 정책은 '그 동작들을 어떤 규칙으로 다룰지에 대한 상위 설정'입니다. 새 환경에서 일을 시작할 때 /policies 와 /permissions 를 한 번 점검해 두면, 이후의 자동 승인 범위가 의도대로 잡혔는지 확신할 수 있습니다.

MCP와 GitHub 연동

Gemini CLI를 외부 도구·데이터로 잇는 통로가 MCP(Model Context Protocol)입니다. /mcp 로 연결된 MCP 서버를 확인·관리합니다. DB·사내 API·검색 같은 외부 능력을 표준 방식으로 붙이는 자리입니다. 어떤 도구든 'MCP 서버' 형태로 표준화해 꽂으면, Gemini는 그걸 자기 도구처럼 씁니다.

MCP가 의미 있는 이유는 '확장이 한 도구에 갇히지 않는다'는 데 있습니다. 같은 MCP 서버를 여러 터미널 AI가 공유할 수 있고, 한 번 만든 연동을 표준으로 재사용할 수 있습니다. 확장형 도구의 철학과 가장 잘 맞는 통합 지점이 바로 여기입니다.

코드 작업의 단골 통합은 GitHub입니다. /setup-github 으로 GitHub 연동을 설정하면, 이슈·PR 흐름과 Gemini의 작업을 이어 붙일 수 있습니다. 여기에 1·2장에서 다진 메모리·스킬·확장을 얹으면, '읽고 계획하고 고치고 PR까지'가 한 터미널 안에서 돌아갑니다.

통합은 늘릴수록 강력하지만, 늘릴수록 관리 비용이 붙습니다. 새 MCP 서버나 연동을 붙일 때는 '이게 매주 실제로 쓰는 통합인가'를 먼저 물어보세요. 한두 번 쓰고 방치되는 연동은 컨텍스트만 차지하고 보안 표면만 넓힙니다. 통합은 모으는 게 아니라 고르는 일입니다.

스킬·확장을 팀에 배포하기

혼자 쓰는 스킬은 ~/.gemini/skills/ 에 두면 그만이지만, 팀이 같은 방식으로 일하게 하려면 배포 단위가 달라집니다. 저장소에 종속된 규칙은 워크스페이스 스코프(.gemini/skills/)에 두어 버전 관리에 함께 올리고, 여러 저장소·팀에 퍼뜨릴 능력은 Extension으로 묶어 배포합니다.

왜 스코프를 의식해서 배포해야 할까요. 같은 스킬이라도 어디 두느냐에 따라 '누가, 어디서' 그 능력을 갖게 되는지가 달라지기 때문입니다. 워크스페이스에 둔 스킬은 그 저장소를 클론한 사람이라면 누구나 자동으로 갖게 되고, 사용자 스코프에 둔 스킬은 그 사람의 모든 프로젝트에만 따라다닙니다.

팀 배포에서 가장 흔한 실수는 '나만의 사용자 스코프 스킬'을 팀 공통이라고 착각하는 것입니다. 내 ~/.gemini/skills/ 에만 있는 스킬은 동료의 터미널엔 없습니다. 팀이 공유해야 할 절차라면 반드시 워크스페이스 스코프나 Extension처럼 '함께 따라오는' 위치에 두어야 합니다.

배포 단위를 정할 때 기준은 '범위'입니다. 이 저장소에서만 의미 있나 → 워크스페이스. 여러 저장소에 공통인가 → Extension. 나 개인 습관인가 → 사용자 스코프. 이 세 갈래만 매번 의식하면, 스킬이 '있어야 할 곳에 없는' 사고를 막을 수 있습니다.

훅으로 라이프사이클에 끼어들기

스킬과 확장이 '능력'이라면, 훅(Hooks)은 '그 능력이 도는 흐름의 특정 시점에 자동으로 끼어드는 장치'입니다. /hooks 로 라이프사이클 훅을 관리합니다. 작업의 정해진 단계마다 미리 정한 동작을 자동으로 거는 자리입니다.

훅이 유용한 이유는 '사람이 매번 기억해야 하는 일'을 자동화로 옮길 수 있어서입니다. 예컨대 변경 흐름의 특정 시점에 검증을 거는 식으로, 매번 손으로 챙기던 절차를 흐름 안에 박아 넣으면 빠뜨릴 일이 없어집니다. 자동화의 신뢰도는 '사람의 기억력'이 아니라 '시스템에 박힌 규칙'에서 나옵니다.

다만 훅은 양날의 칼입니다. 자동으로 끼어드는 만큼, 잘못 걸면 의도치 않은 시점에 동작이 실행됩니다. 새 훅을 추가할 때는 어떤 라이프사이클 시점에 무엇이 실행되는지를 분명히 해두고, /hooks 로 등록 상태를 확인하는 습관이 안전합니다.

권한·정책과 함께 보면 그림이 완성됩니다. 권한이 '무엇을 허용할지', 훅이 '언제 무엇을 자동으로 할지'를 정합니다. 둘을 함께 설계하면 '안전한 자동화'와 '편한 자동화' 사이의 균형을 의도대로 잡을 수 있습니다.

컨텍스트와 비용을 관리하기

확장형 도구를 오래 굴리면 대화가 길어지고 컨텍스트가 무거워집니다. 그러면 응답이 느려지고, 모델이 앞부분 맥락을 놓치기 시작합니다. /compress 로 대화를 압축해 컨텍스트를 확보하고, 흐름이 완전히 바뀌는 새 작업에 들어갈 땐 /clear 로 비우고 새로 시작합니다.

왜 의식적으로 관리해야 하느냐면, 컨텍스트는 '쌓을수록 좋은' 것이 아니기 때문입니다. 지금 작업과 무관한 옛 대화가 많이 남아 있으면, 모델은 그 노이즈까지 고려하느라 오히려 흐려집니다. 긴 세션 중간중간 압축하거나, 주제가 바뀌면 깨끗이 비우는 편이 결과가 더 좋습니다.

되돌리기 도구도 함께 알아두면 좋습니다. /rewind 로 이전 지점으로 되돌리고, /restore 로 이전 상태를 복원하며, /chat 과 /resume 으로 대화를 저장하고 이어갑니다. 작업을 잠시 멈췄다 다시 잡거나, 실험적으로 시도했다가 되돌릴 때 흐름을 잃지 않게 해줍니다.

비용 측면에서도 같은 원칙이 통합니다. 불필요하게 큰 컨텍스트는 그만큼의 처리량을 쓰므로, '필요한 맥락만 들고 가는' 습관이 곧 비용 관리입니다. /stats 로 세션 통계를 보며 흐름을 점검하고, 작업 단위로 컨텍스트를 끊어 가는 운영이 길게 보면 가장 깔끔합니다.

설치·로그인이 안 풀릴 때

가장 흔한 첫 벽은 'gemini: command not found'입니다. 대개 Node가 20 미만이거나, 전역 npm bin 경로가 PATH에 없는 경우입니다. Node를 20 이상으로 올리거나 Homebrew로 설치하면 정리되고, 설치 자체가 번거롭다면 'npx @google/gemini-cli'로 설치 없이 바로 실행할 수도 있습니다.

로그인 문제는 이제 성격이 달라졌습니다. '구글 계정 무료 로그인이 안 된다'는 더 이상 버그가 아니라 정상입니다 — 무료 티어가 종료됐기 때문입니다(시작하기). 키를 설정했는데도 막힌다면 /auth 로 인증 방식을 다시 고르고, GEMINI_API_KEY 철자와 '제한된 키' 여부(2026년 6월 이후 제한 없는 키는 거부됨)를 확인하세요.

지원 지역과 환경도 한 번 봅니다. Gemini CLI는 지원 리전과 OS·Node 버전을 전제로 동작합니다. '되는 사람은 되고 나는 안 되는' 상황이라면, 같은 코드보다 환경(리전·Node·키 종류)을 먼저 의심하는 편이 빠릅니다.

정리하면 첫날 문제는 거의 셋입니다 — Node·PATH(설치), 인증 방식(/auth·제한된 키), 그리고 무료 티어 종료라는 전제 변화. 앞의 둘은 고치는 것이고, 마지막 하나는 '이제 그렇게 동작한다'를 받아들이는 것입니다.

한도(429)에 부딪힐 때

'429 / rate limit exceeded'는 요청 한도를 넘었다는 신호입니다. 무료·미결제 키는 한도가 빠듯하니, 창이 리셋될 때까지 기다리거나 더 가벼운 모델로 내리거나 결제된 키로 바꾸는 선택지가 있습니다.

한 가지 알려진 함정이 있습니다. 유료 계정으로 로그인돼 있는데도 한도가 이상하게 빨리 닳는다면, 환경에 설정된 AI Studio 무료 키(GEMINI_API_KEY)가 계정 등급을 덮어쓰고 있을 수 있습니다. 이때는 그 키를 잠시 환경 변수에서 제거해 계정 인증으로 돌리거나, 결제된 키로 교체하면 풀립니다.

지금 어떤 인증·한도로 도는지 헷갈리면 /auth 로 현재 방식을 확인하고, /stats 로 사용량을 들여다봅니다. '왜 안 되지'를 막연히 반복하기 전에, 어떤 키로 어느 한도에서 돌고 있는지부터 눈으로 보는 것이 먼저입니다.

꾸준히 한도에 부딪힌다면 경로 자체를 바꿀 때입니다. 개인 실험을 넘어 매일 쓴다면 Vertex나 Code Assist 같은 유료 좌석이 한도와 안정성 모두에서 낫습니다(시작하기).

느리거나 컨텍스트가 무거울 때

세션이 느려지고 답이 흐려진다면 대개 컨텍스트가 무거워진 탓입니다. /stats 로 토큰 현황을 확인하고, /compress 로 대화를 요약해 여유를 만들거나, 주제가 바뀌었으면 /clear 로 비우고 새로 시작하세요(4장).

확장과 도구도 무게입니다. 안 쓰는 Extensions나 MCP 서버를 붙여 두면 매 턴 컨텍스트를 잡아먹습니다. /extensions 와 /tools, /mcp 로 지금 무엇이 붙어 있는지 보고, 이 작업에 필요 없는 것은 떼어 두는 절제가 속도와 비용 모두에 이롭습니다.

GEMINI.md도 너무 길면 부담입니다. 매 프롬프트에 함께 실리므로, 핵심 규칙만 남기고 군더더기를 덜어내는 편이 좋습니다. '필요한 것만 연결하고 핵심만 적는다'가 확장형 도구를 가볍게 유지하는 기본기입니다(4장).

느려졌다고 곧장 더 무거운 모델을 켜는 건 대개 정반대 처방입니다. 원인은 모델이 아니라 컨텍스트일 때가 많으니, 책상부터 정리한 뒤 그래도 부족하면 그때 모델을 손대세요.

복구하고, 신고하기

대화를 잃지 않으려면 /chat save <태그>로 저장해 두고, 나중에 /chat resume <태그>로 이어가면 됩니다. /chat list 로 저장된 대화를 봅니다. 도구가 파일을 엉뚱하게 바꿨다면 /restore 로 도구 실행 직전 상태로 프로젝트를 되돌릴 수 있습니다.

도구 자체의 버그로 보이면 /bug 로 깃허브 이슈를 바로 생성할 수 있고, /about 으로 나온 버전 정보를 함께 적으면 처리가 빠릅니다. 공식 저장소(github.com/google-gemini/gemini-cli)의 이슈와 디스커션도 같은 문제를 겪는 사람들의 해법이 모이는 곳입니다.

복구가 잦다면 습관을 점검할 때입니다. 큰 변경은 계획을 먼저 받고(3장), 도구 실행 전 승인을 눈으로 읽으며 진행하면 애초에 크게 되돌릴 일이 줄어듭니다. /restore 가 있다고 해서 확인을 건너뛰면, 결국 되돌리는 데 더 많은 시간을 씁니다.

마지막으로, 이 장의 문제 절반은 1·2장을 건너뛴 결과입니다. 메모리(GEMINI.md)와 스킬·확장을 먼저 갖춰 두면 막힐 일 자체가 크게 줄어듭니다. 막힐 때 펴보는 장이지만, 진짜 처방은 앞 장에 있는 셈입니다.