제미나이 CLI 오류는 설치 직후부터 일상적인 사용 중에도 예고 없이 튀어나오는데, 원인을 정확히 알지 못하면 같은 실수를 반복하게 됩니다. 이 글에서는 가장 자주 발생하는 오류 유형과 단계별 해결법, 그리고 구글 AI 도구를 장기적으로 안전하게 활용하는 실전 노하우까지 한 번에 정리합니다.
1. 제미나이 CLI란 무엇인가
제미나이 CLI(Gemini CLI, Command Line Interface)는 구글이 2025년에 공개한 오픈소스 AI 에이전트로, 터미널에서 바로 Gemini 모델에 접근해 작업을 수행할 수 있는 도구입니다. 웹 브라우저 없이도 코드 작성, 버그 수정, 파일 조작, 콘텐츠 생성 등 다양한 작업을 명령어 한 줄로 처리할 수 있다는 점이 가장 큰 매력이죠. 기존의 커서(Cursor) 에디터나 Claude 데스크탑 앱과 비교해도 손색없을 만큼 강력한 기능을 갖추고 있어, 개발자들 사이에서 빠르게 화제가 됐습니다.
특히 추론 및 행동 루프(ReAct, Reasoning and Acting)를 기반으로 동작하기 때문에, 단순한 질문 답변을 넘어 복잡한 다단계 작업도 처리할 수 있습니다. 로컬 또는 원격 MCP(Model Context Protocol) 서버와 연동하면 기능이 훨씬 확장되고요. 개인용 Gemini Code Assist를 비롯해 Standard, Enterprise 플랜에서도 제미나이 CLI를 사용할 수 있는 할당량을 제공합니다. 무료 API 키만으로도 처음 시작하기에 충분한 양이 주어지기 때문에, 입문 장벽이 낮다는 것도 장점입니다.
처음 사용해보는 분들이 종종 헷갈리는 부분이 있습니다. 제미나이 CLI는 웹 브라우저에서 접속하는 gemini.google.com과는 다른 도구입니다. CLI는 터미널 기반이라서 별도 설치가 필요하고, 설정 과정에서 제미나이 CLI 오류가 가장 많이 발생합니다. 아래에서 유형별로 하나씩 살펴보겠습니다.
| 구분 | 제미나이 CLI | 웹 제미나이(gemini.google.com) |
|---|---|---|
| 접근 방식 | 터미널(명령줄) | 웹 브라우저 |
| 설치 필요 | 필요(Node.js, npm 등) | 불필요 |
| 파일 조작 | 가능 | 제한적 |
| 자동화 | 고급 자동화 가능 | 수동 인터랙션 위주 |
| 주요 오류 유형 | 설치/인증/PATH/API 키 | 세션/서버/계정 인증 |
앤트로픽 프롬프트 캐싱 토큰 비용 90% 절약 완벽 가이드
2. 설치 오류 해결법 (ENOENT, Git PATH 문제)
제미나이 CLI 오류 중 가장 먼저 맞닥뜨리는 것이 설치 단계의 오류입니다. 특히 윈도우(Windows) 환경에서 npm을 통해 설치할 때 “code ENOENT” 또는 “syscall spawn git” 오류가 뜨는 경우가 많습니다. 이 오류는 Git이 시스템에 설치되어 있지 않거나, 설치되어 있더라도 PATH 환경 변수에 Git 실행 파일 경로가 올바르게 등록되지 않았을 때 발생합니다.
해결 순서는 간단합니다. 먼저 터미널에서 git –version 명령어를 입력해 Git이 정상 인식되는지 확인합니다. 오류가 뜬다면 git-scm.com에서 운영 체제에 맞는 Git을 설치하세요. 설치 후에도 문제가 계속된다면 PATH에 Git 경로(예: C:\Program Files\Git\bin)를 수동으로 추가해야 합니다. 이 작업 후에는 반드시 터미널을 완전히 종료하고 다시 시작해야 변경 사항이 적용됩니다.
윈도우에서 PowerShell 실행 정책 문제로 설치가 막히는 경우도 있습니다. 이때는 PowerShell을 관리자 권한으로 열고 Set-ExecutionPolicy RemoteSigned를 입력한 다음 ‘y’를 선택하면 해결됩니다. 맥(Mac) 환경에서는 설치 명령어 앞에 sudo를 붙여서 실행하면 대부분의 권한 오류가 해결됩니다. 지인도 처음에 이 과정에서 여러 번 막혔는데, PATH 환경 변수 설정 하나로 한 번에 해결됐다며 “이게 다였냐”고 허탈해했을 정도예요.
| 오류 코드/메시지 | 원인 | 해결법 |
|---|---|---|
| ENOENT / syscall spawn git | Git 미설치 또는 PATH 미등록 | Git 설치 후 PATH 추가, 터미널 재시작 |
| 실행 정책 오류 (Windows) | PowerShell 보안 정책 | Set-ExecutionPolicy RemoteSigned |
| 권한 오류 (Mac) | 관리자 권한 부족 | 명령어 앞에 sudo 추가 |
| Node.js 버전 오류 | 구버전 Node.js 사용 | Node.js 최신 LTS 버전으로 업데이트 |
3. 인증 오류 해결법 (로그인 실패, API 키 오류)
설치는 성공했는데 제미나이 CLI 오류가 로그인 단계에서 발생하는 경우도 꽤 많습니다. 터미널에서 gemini를 입력했을 때 구글 계정 연동은 성공했지만, “클라우드 프로젝트가 등록되어 있지 않다”는 메시지가 뜨거나, API 키 인증에서 막히는 상황입니다. 이럴 때는 구글 클라우드 콘솔에서 프로젝트를 하나 생성하고, 해당 프로젝트에 Gemini API를 활성화해주면 해결됩니다.
API 키 관련 오류 중에는 “Your API key was reported as leaked”라는 메시지가 뜨는 경우도 있습니다. 이는 API 키가 공개 저장소나 외부에 노출된 것으로 구글이 판단하여 선제적으로 차단한 경우입니다. 해결책은 간단합니다. Google AI Studio에서 기존 키를 삭제하고 새로운 API 키를 발급받으면 됩니다. 발급받은 키는 절대로 GitHub 등 공개 저장소에 올리면 안 됩니다. 환경 변수(GEMINI_API_KEY)로 관리하는 것이 가장 안전합니다.
API 키를 사용하는 방식이 구글 계정 로그인 방식보다 오히려 안정적인 면이 있습니다. 무료로 발급받으면 처음에 상당한 양의 할당량을 제공하며, 터미널에서 /auth 명령어를 입력한 뒤 API 버전을 선택하면 연결이 완료됩니다. 시스템 환경 변수에 GEMINI_API_KEY를 등록해두면 제미나이 CLI 실행 시 자동으로 인식됩니다.
| 오류 유형 | 증상 | 해결법 |
|---|---|---|
| API 키 유출 차단 | “API key reported as leaked” | Google AI Studio에서 새 키 발급 |
| 클라우드 프로젝트 미연결 | 로그인 성공 후 접근 불가 | 구글 클라우드 콘솔에서 프로젝트 생성 및 API 활성화 |
| 계정 연령 미인증 | 앱 또는 CLI 실행 불가 | 구글 계정 연령 인증 페이지에서 인증 완료 |
4. 실행 중 발생하는 오류 해결법 (오류 코드 3, 5, 세션 문제)
제미나이 CLI를 잘 쓰다 보면 사용 중에 갑자기 제미나이 CLI 오류가 발생하기도 합니다. 특히 웹 제미나이에서는 오류 코드 3과 오류 코드 5가 자주 보고됩니다. 오류 코드 3은 채팅 세션 데이터의 동기화 문제입니다. 특정 채팅방에서만 반복적으로 발생하고, 새 채팅을 열면 정상 작동하는 것이 특징입니다. 해당 채팅방 자체가 손상된 상태이기 때문에, 같은 채팅에서 새로고침을 반복해도 해결되지 않습니다. 손상된 세션은 사용자가 복구할 수 없으므로, 새 채팅을 시작하는 것이 유일한 해결책입니다.
오류 코드 5는 구글 서버 측 과부하나 일시적 장애입니다. 사용자 환경이나 브라우저 문제가 아니므로, 10~20분 기다렸다가 다시 시도하는 것이 최선입니다. 구글 서비스 상태는 Google Workspace Status 페이지나 StatusGator 같은 서비스에서 실시간으로 확인할 수 있습니다. CLI 환경에서도 비슷한 증상이 나타날 수 있는데, 대화가 길어질수록 컨텍스트 윈도우가 차서 응답이 느려지거나 터미널이 갑자기 종료되는 경우가 생깁니다. 이를 방지하려면 /clear 명령어로 대화를 주기적으로 초기화하거나, /compress 명령어로 토큰 사용량을 줄여주는 것이 좋습니다.
실제로 CLI를 활발히 쓰는 한 개발자 지인도 이 문제를 겪었는데, 세션이 길어질수록 응답 품질이 눈에 띄게 떨어지고 엉뚱한 답변이 나오기 시작했다고 합니다. /memory 명령어로 중요 규칙을 장기 기억에 저장해두고, 세션을 자주 재시작하는 방식으로 바꾼 뒤부터는 훨씬 일관된 결과를 얻게 됐다고 하더라고요.
| 오류 코드 | 원인 | 해결법 |
|---|---|---|
| 오류 코드 3 | 채팅 세션 동기화 손상 | 새 채팅 시작 (기존 채팅 복구 불가) |
| 오류 코드 5 | 구글 서버 과부하 또는 일시 장애 | 10~20분 대기 후 재시도 |
| 컨텍스트 오버플로우 | 대화 길이 초과 (토큰 부족) | /clear 또는 /compress 명령어 사용 |
| 터미널 갑작스러운 종료 | 컨텍스트 80% 이상 사용 | 세션 자주 재시작, /memory로 규칙 저장 |
5. 구글 AI 도구를 안전하게 사용하는 핵심 설정법
제미나이 CLI 오류를 줄이고 안전하게 사용하려면 올바른 설정이 핵심입니다. 제미나이 CLI에는 settings.json이라는 설정 파일이 존재합니다. 글로벌 설정은 ~/.gemini/settings.json에, 프로젝트별 지역 설정은 해당 프로젝트 디렉터리의 .gemini/settings.json에 위치합니다. 지역 설정이 글로벌 설정보다 우선순위가 높으므로, 프로젝트마다 별도의 규칙을 적용하고 싶다면 이 구조를 활용하면 됩니다.
보안 측면에서 가장 중요한 규칙 하나는 delete 명령을 절대 ‘always(항상 허용)’로 열어두지 않는 것입니다. 제미나이 CLI는 기본적으로 파일 수정 시마다 사용자에게 확인을 요청하는 안전한 구조지만, delete 명령을 항상 허용으로 설정하면 리팩토링 도중 원본 파일을 갑자기 삭제하고 “찾을 수 없다”고 답변하는 상황이 생길 수 있습니다. 휴지통에서도 복구되지 않는 경우가 있으니 반드시 Git 백업을 함께 운용하세요. Git은 이런 상황을 위한 가장 기본적인 안전망입니다.
GEMINI.md 파일도 꼭 활용해야 합니다. 이 파일은 제미나이 CLI의 규칙 파일로, 프로젝트 디렉터리 또는 ~/.gemini/ 경로에 배치하면 됩니다. 예를 들어 “윈도우 명령어만 사용할 것”, “네임스페이스를 지정하지 않으면 리소스를 생성하지 말 것” 같은 규칙을 써두면, 이후 세션에서 매번 설명하지 않아도 일관되게 적용됩니다. 이 파일이 제대로 읽히고 있다면 CLI 실행 시 “Using 1 GEMINI.md file”이라는 메시지가 표시됩니다.
| 설정 항목 | 권장 방법 | 이유 |
|---|---|---|
| API 키 관리 | 환경 변수(GEMINI_API_KEY)로 관리 | 공개 노출 방지 |
| delete 명령 권한 | ‘always’ 허용 금지 | 실수로 인한 파일 삭제 방지 |
| GEMINI.md 규칙 파일 | 프로젝트별 규칙 작성 | 일관된 AI 동작 유지 |
| 백업 | Git 연동 필수 | 파일 손실 시 복구 가능 |
| 세션 관리 | /memory로 장기 기억 저장, 자주 재시작 | 응답 품질 유지 |
자주 묻는 질문
제미나이 CLI 설치 후 ‘gemini’ 명령어가 인식되지 않을 때는 어떻게 하나요?
npm으로 설치했다면 npm의 전역 바이너리 경로가 시스템 PATH에 등록되어 있지 않을 가능성이 높습니다. 터미널을 완전히 닫고 다시 열어보고, 그래도 안 된다면 npm의 글로벌 설치 경로(npm root -g 명령어로 확인)를 시스템 환경 변수 PATH에 수동으로 추가해보세요. 윈도우의 경우 시스템 속성 → 고급 → 환경 변수에서 수정할 수 있습니다.
제미나이 CLI 오류 중 ‘할당량 초과(Quota Exceeded)’ 메시지가 떴을 때 어떻게 하나요?
무료 API 키는 분당 요청 수와 일일 요청 수에 제한이 있습니다. 잠시 기다리면 할당량이 리셋됩니다. 작업량이 많다면 Google AI Studio에서 유료 플랜을 검토하거나, Gemini Code Assist 구독을 통해 더 높은 할당량을 받을 수 있습니다. 무료 API는 데이터가 학습에 활용될 수 있다는 점도 고려해서 민감한 코드 작업 시에는 유료 플랜 사용을 권장합니다.
제미나이 CLI에서 컨텍스트가 길어지면 왜 갑자기 터미널이 종료되나요?
컨텍스트 윈도우 사용량이 80% 이상 도달하면 모델 응답 품질이 저하되고, 세션이 불안정해져 터미널이 갑자기 종료되는 현상이 발생합니다. 이를 방지하려면 /compress 명령어로 대화 내용을 요약 압축하거나, /clear로 대화를 초기화하고 재시작하는 것이 좋습니다. 중요한 규칙이나 설정은 /memory add 명령어로 장기 기억에 저장해두면 재시작 후에도 유지됩니다.
구글 계정 연령 인증이 왜 제미나이 오류와 관련이 있나요?
구글은 AI 서비스 이용 시 성인 여부를 확인하는 정책을 적용합니다. 연령 인증이 완료되지 않은 상태에서는 Gemini 앱 및 일부 기능에서 “문제가 발생했습니다” 오류가 발생할 수 있습니다. 앱 재설치, VPN 해제, 캐시 삭제 등 일반적인 방법으로 해결되지 않는다면 구글 계정 연령 인증 페이지에서 본인 인증을 완료한 후 앱을 재실행해보세요.
제미나이 CLI에서 파일을 다루다 실수로 삭제했을 때 복구할 수 있나요?
안타깝게도 제미나이 CLI가 삭제한 파일은 일반적으로 휴지통에 남지 않는 경우가 많습니다. 이 때문에 파일 작업 전에 반드시 Git으로 커밋을 해두거나, 중요한 디렉터리는 별도로 백업해두는 습관이 필요합니다. 또한 delete 명령 허용 설정을 ‘always’로 열어두지 않고, 매번 확인 단계를 거치도록 설정하는 것이 사고를 예방하는 가장 좋은 방법입니다.
윈도우와 맥에서 제미나이 CLI 설정 파일 경로가 다른가요?
글로벌 설정 파일(settings.json)은 두 환경 모두 홈 디렉터리의 ~/.gemini/settings.json에 위치합니다. 윈도우에서는 C:\Users\사용자명\.gemini\settings.json이 해당 경로입니다. 프로젝트별 지역 설정은 현재 작업 디렉터리의 .gemini/settings.json에 위치하며, 글로벌 설정보다 우선 적용됩니다. 시스템 전역 설정은 GEMINI_CLI_SYSTEM_SETTINGS_PATH 환경 변수로 경로를 별도 지정할 수도 있습니다.
글을 마치며
제미나이 CLI 오류는 대부분 설치 환경 설정, 인증, 세션 관리 이 세 가지 영역에서 발생합니다. 처음에는 낯설고 당황스럽지만, 원인을 알고 나면 생각보다 빠르게 해결할 수 있습니다. 핵심은 Git 백업을 항상 유지하고, API 키는 환경 변수로 안전하게 관리하며, 세션이 길어지기 전에 /compress나 /clear로 주기적으로 정리하는 습관을 들이는 것입니다. GEMINI.md 규칙 파일까지 잘 활용하면 제미나이 CLI는 개발, 문서 작성, 자동화 등 다양한 분야에서 정말 강력한 도구가 됩니다. 처음 접하는 분이라면 오류에 좌절하지 말고, 이 글에서 소개한 순서대로 하나씩 확인해보세요. 분명 훨씬 빠르게 안정적인 환경을 만들 수 있을 겁니다.