핵심 요약
- npm 설치가 끝난 뒤 "'gemini'은(는) 내부 또는 외부 명령이 아닙니다"가 나오면 설치가 깨진 게 아니라 PATH 문제입니다. npm config get prefix를 실행하고, 출력된 폴더(C:\Users\<사용자>\AppData\Roaming\npm)를 사용자 PATH에 추가한 뒤 터미널을 다시 여세요.
- 로그인할 때 "This account requires setting the GOOGLE_CLOUD_PROJECT env var"가 뜬다면? 개인 무료·AI Pro·AI Ultra 계정은 설정할 필요가 없습니다. 필요한 것은 Workspace 계정, Code Assist 라이선스 시트, 18세 미만, 미지원 지역뿐입니다.
- "Not eligible for Gemini Code Assist for individuals … 18 years old or older"는 Google 계정의 나이가 확인되지 않았다는 뜻입니다. Google 나이 상태 페이지에서 나이 확인을 마친 뒤 gemini를 다시 실행해 로그인하세요.
- 로그인을 두 번 실패해 막혔다면 OAuth에 매달리지 말고 AI Studio에서 Gemini API 키를 발급받아 GEMINI_API_KEY로 내보내세요 — 별도의 무료 한도가 있습니다. 인증 실패 종료 코드는 41입니다.
How to Fix Gemini CLI is Not Recognized Error in Windows (Step by Step)
채널: Web Tech Knowledge4:38
Several error issues encountered when logging into Gemini CLI with a Google account
채널: AttackOnLife2:56
Troubleshooting — official documentation
공식 문서: google-gemini.github.io
Authentication setup — official documentation
공식 문서: google-gemini.github.io
이 페이지의 모든 명령어, 오류 메시지, 대화상자는 Gemini CLI 공식 인증·문제 해결 문서와 대조했습니다. Windows 녹화가 설치와 PATH 복구의 시각적 소스이고, macOS 녹화가 실제 Google 계정 로그인 오류 두 건과 이를 해소하는 나이 확인 흐름의 정보 소스입니다.
스크린샷 저작권은 각 제작자에게 있으며 해당 타임스탬프로 연결됩니다. 얼굴이 나오는 장면은 사용하지 않았습니다.
Gemini CLI 고치기, 단계별 가이드
파트 1 — "'gemini'은(는) 인식되지 않음": Windows PATH 복구
- 1
먼저 오류를 그대로 재현한다
녹화에서는 npm install -g @google/gemini-cli가 말끔히 끝났고(변경된 패키지 577개, 4분), 그런데도 gemini를 입력하면 "'gemini'은(는) 내부 또는 외부 명령, 실행 가능한 프로그램, 또는 배치 파일이 아닙니다"가 돌아옵니다. VS Code 터미널에서도 마찬가지고요. 이 문구가 바로 PATH 문제의 특징입니다. 패키지는 설치됐지만 Windows는 npm이 런처를 둔 위치를 전혀 모릅니다.
577개 패키지 설치 후에도 gemini는 "인식되지 않음" — 깨진 설치가 아니라 PATH 증상입니다.0:08부터 보기 - 2
npm에게 전역 런처 위치를 묻는다
npm config get prefix를 실행하세요. 전역 패키지가 놓이는 폴더가 출력되는데, 여기서는 C:\Users\User\AppData\Roaming\npm입니다. gemini 명령이 바로 이 폴더에 살고, PATH에서 빠진 것도 이 폴더입니다. 적어두거나 클립보드에 담아두세요.
npm config get prefix가 C:\Users\User\AppData\Roaming\npm을 출력 — PATH에 필요한 폴더입니다.0:54부터 보기 - 3
파일 탐색기에서 AppData 표시하기
npm 폴더는 사용자 프로필의 AppData 아래에 있고, Windows는 기본적으로 이를 숨깁니다. 파일 탐색기에서 C:\Users\User로 가서 보기 > 표시를 열고 숨긴 항목에 체크하세요. 녹화도 정확히 이렇게 하고 AppData가 바로 목록에 나타납니다.
보기 > 표시 > 숨긴 항목에 체크하면 C:\Users\User 아래에 AppData가 나타납니다.1:30부터 보기 - 4
npm 폴더에 런처가 있는지 확인한다
AppData > Roaming > npm으로 들어가세요. 그 안에는 gemini.cmd — gemini 명령이 실제로 실행하는 Windows 명령 스크립트 — 가 Unix 셸용 gemini, node_modules와 나란히 있습니다. 이 파일이 있다는 것은 설치가 성공했고 깨진 것은 PATH뿐이라는 증거입니다.
347바이트 Windows 명령 스크립트 gemini.cmd가 AppData\Roaming\npm에 있습니다.2:02부터 보기 - 5
환경 변수 대화상자 열기
시작 메뉴에서 "환경 변수"를 검색해 "시스템 환경 변수 편집"을 열고 환경 변수 버튼을 누르세요. 아래쪽 절반이 시스템 변수이고, 위쪽 절반 — 녹화에서 커서가 PATH를 가리키는 곳 — 이 이 계정의 사용자 변수입니다. 사용자 단위 npm 폴더라면 사용자 변수의 PATH가 맞는 자리입니다.
환경 변수 대화상자, 사용자 변수의 PATH에 커서를 둔 상태.2:38부터 보기 - 6
npm 폴더를 PATH 새 항목으로 추가한다
PATH를 선택하고 편집, 새로 만들기를 차례로 누른 뒤 2단계의 npm 접두사 — C:\Users\User\AppData\Roaming\npm — 를 붙여넣으세요. 열려 있는 모든 대화상자에서 확인을 누릅니다. 녹화 목록에는 Python, Ollama, VS Code 항목이 이미 있고 새 빈 행은 그 아래에 붙습니다. 순서는 이 수정에 영향을 주지 않습니다.
환경 변수 편집 대화상자: 빈 PATH 항목이 선택된 상태, npm 폴더를 붙여넣기 직전.3:01부터 보기
파트 2 — 로그인 실패: Google 계정 오류 두 가지 걷어내기
- 7
Google 계정 로그인 오류 두 가지를 알아본다
PATH가 고쳐지면 gemini가 실행되며 로그인 방식을 묻습니다 — "Login with Google"을 고르세요. 두 번째 녹화는 실제 로그인을 막는 두 가지 실패를 보여줍니다. 첫째: "Failed to login. Message: This account requires setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID env var." 둘째: "Failed to login. Message: Your current account is not eligible for Gemini Code Assist for individuals. To use Gemini Code Assist for individuals you must be 18 years old or older."
Failed to login 원문 그대로: GOOGLE_CLOUD_PROJECT 요구와 18세 이상 자격 거부.0:35부터 보기 - 8
필요 없으면 GOOGLE_CLOUD_PROJECT를 설정하지 않는다
녹화에 등장하는 유지관리자 토론 #13516 "Clarifying Authentication and Google Cloud Project Settings"는 이 변수가 필요한 조건을 정리합니다. 무료 계정, AI Pro, AI Ultra로 개인 로그인할 때는 설정하면 안 됩니다. 필요한 것은 Workspace 계정, Code Assist 라이선스 시트, 18세 미만, 무료 티어 미지원 지역 계정입니다. 개인 플랜인데 설정해뒀다면 변수를 빼고 다시 로그인하세요.
gemini-cli 토론 #13516: 무료·AI Pro·AI Ultra 계정에서 GOOGLE_CLOUD_PROJECT를 설정하면 안 되는 경우.1:05부터 보기 - 9
거부당했다면 나이 확인을 진행한다
"not eligible … 18 years old or older" 거부는 실제 생일 문제가 아니라 '확인된' 생일 문제입니다. 녹화의 계정은 나이 확인이 없어서 Google이 나이 상태 페이지에 "Your age isn't confirmed"와 파란 Verify your age 버튼을 보여줍니다. 이 흐름을 마치면(제작자는 여권을 사용) gemini를 다시 실행해 Login with Google을 고르세요 — 방금 실패한 같은 로그인이 이번엔 통과합니다.
"Your age isn't confirmed"와 Verify your age 버튼 — 한 번만 마치면 로그인이 통과됩니다.1:35부터 보기
파트 3 — 새 터미널에서 해결 확인하기
- 10
새 명령 프롬프트에서 다시 실행한다
PATH 수정 전에 열린 터미널은 예전 PATH를 그대로 가집니다. 열린 창을 모두 닫고 새 명령 프롬프트를 시작한 뒤 gemini를 입력하세요. ASCII GEMINI 배너와 시작 팁이 나타나고, 홈 디렉터리에서 실행 중이므로 프로젝트 전용 디렉터리 권고 문구도 보입니다 — 오류가 아니라 경고입니다.
첫 성공 실행: 명령 프롬프트의 GEMINI 배너와 시작 팁.4:08부터 보기 - 11
VS Code에서도 되는지 확인한다
녹화는 VS Code에서 끝납니다. 실제 프로젝트 폴더(G:\TestProject)에서 터미널을 열어 gemini를 실행하면 배너가 출력되고, 바닥글에 "no sandbox", 커서는 "Type your message or @path/to/file"에서 대기합니다. PATH 수정 중 VS Code가 켜져 있었다면 먼저 닫았다 다시 여세요 — 명령 프롬프트와 같은 규칙입니다.
G:\TestProject의 VS Code 터미널에 GEMINI 배너와 입력 상자.4:32부터 보기
그래도 안 된다면 — Gemini CLI의 드문 원인들
PATH와 두 로그인 오류가 대부분의 사례를 커버합니다. 그 후에도 Gemini CLI가 멈추거나 느리거나 오류가 난다면 이 목록을 위에서부터 처리하세요:
- 1추측 대신 재설치. 공식 문제 해결 문서는 PATH/npm 계열 파손에 대해 npm install -g @google/gemini-cli@latest 재실행을 안내합니다. 녹화도 시스템 PATH에 Node.js 자체가 남아 있는지 확인하고요. Node가 지워졌거나 npm이 반쯤 업데이트된 상태라면 gemini.cmd는 아무것도 가리키지 못합니다.
- 2"Initializing"에서 멈추거나 인증을 기다리나요? 그 화면은 OAuth 브라우저 흐름이 끝나기를 기다리는 중입니다. 브라우저 탭이 열리지 않았다면 gemini를 다시 실행하고 안내된 탭에서 Login with Google을 마치세요. 프록시나 오프라인 네트워크는 정확히 이 단계에서 붙잡아 둡니다.
- 3인증이 계속 실패하나요? 로그인 실패는 종료 코드 41로 끝나고, 캐시된 Google 자격증명은 ~/.gemini에 있습니다(settings.json 곁의 oauth_creds.json). 캐시 자격증명을 지우고 gemini를 다시 실행해 깨진 세션을 반복 재시도하는 대신 깨끗이 다시 로그인하세요.
- 4OAuth가 아예 끝나지 않나요? 방식을 바꾸세요. 인증 대화상자의 세 번째 선택지가 Google AI Studio의 Gemini API 키입니다. GEMINI_API_KEY로 내보내면 브라우저 흐름을 완전히 건너뜁니다. 공식 문서는 Google 로그인을 먼저 권하지만, API 키는 별도의 무료 티어가 있고 프로젝트나 나이 요건도 없습니다.
- 5모델 접근이나 할당량 오류인가요? Workspace 연동 Gmail 계정은 무료 Code Assist 티어 활성화에 실패할 수 있습니다("Request contains an invalid argument"). 공식 해결책은 GOOGLE_CLOUD_PROJECT에 실제 프로젝트 ID를 설정하거나 API 키로 이동하는 것입니다. 무료 티어 한도는 초기화되며, 유료 AI Pro/Ultra는 상한을 올려줍니다.
- 6VS Code에서만 안 되나요? 그것도 '오래된 터미널' 규칙입니다. VS Code는 시작 시점의 PATH를 물려받으므로 수정 전에 열린 창은 npm 폴더를 보지 못합니다. VS Code를 닫았다 다시 열고(최소한 터미널을 죽이고) gemini를 다시 시도하세요.
위 어느 것도 해당하지 않나요? CLI가 남긴 기록을 읽으세요. 로그와 설정은 ~/.gemini 디렉터리 아래에 있고, --verbose를 붙여 다시 실행하면 출력이 늘어납니다. 공식 문제 해결 페이지의 마지막은 유지관리자와 같습니다 — gemini-cli GitHub 이슈 트래커를 검색한 뒤 버전과 전체 오류 문구를 첨부해 새 이슈를 여세요.