목적별 가이드

하려는 일 가이드
정상 설치·첫 작업 순서 확인 Gemini CLI 첫 사용
로그인·API 키의 한도와 비용 구분 인증 방식별 한도·요금
MCP 서버·도구 단계에서 실패 MCP 설정·연결 확인

어느 단계에서 실패했는지 나누기

실패 지점 먼저 확인할 대상
gemini 명령 자체를 찾지 못함 Node/npm·설치 경로·터미널 PATH
브라우저 로그인·계정 선택 중 실패 인증 방식·계정 종류·제공 지역·프로젝트 자격
입력 후 429·할당량 안내 현재 계정/프로젝트·모델·요청 제한·재시도 안내
MCP가 연결되지 않음 서버 명령·경로·설정 범위·도구 인증
인증서·프록시 관련 연결 실패 현재 네트워크와 Node가 신뢰하는 인증서

오류 문구·발생 시점·CLI/Node 버전·인증 경로를 적어 두면 확인 범위를 줄일 수 있습니다. 로그를 공유할 때는 키·토큰·개인 경로·프로젝트 식별 정보를 먼저 확인하고 공개할 범위를 정하세요.

명령이 없거나 PowerShell에서 실행되지 않을 때

PowerShell에서 현재 실행 파일 경로를 확인합니다.

Get-Command node,npm.cmd,gemini.cmd -ErrorAction SilentlyContinue |
  Select-Object Name,Source
node --version
npm.cmd --version

Node가 없다면 먼저 공식 Node 설치를 확인합니다. Node는 있지만 gemini.cmd가 없으면 설치한 방식·npm 전역 실행 파일 경로·터미널을 다시 열었는지 확인하세요. 여러 Node 관리자를 사용한다면 설치한 환경과 현재 터미널이 같은지도 봅니다.

PowerShell에서 .ps1 실행 정책 오류가 나면 Windows용 .cmd 진입점으로 실행되는지 확인할 수 있습니다.

gemini.cmd --version

조직에서 실행 자체를 제한한 환경에서는 해당 정책을 확인해야 합니다. 실행 정책이나 보안 설정을 일괄 낮추는 조치부터 하지 마세요. 현재 설치 경로가 명확해진 뒤 필요한 경우 같은 설치 방식으로 갱신합니다.

Google 로그인과 계정 자격 확인하기

개인 Google 로그인·조직 계정·API 키·Vertex AI는 필요한 설정이 다릅니다. /auth에서 어떤 경로를 선택했는지 확인하고, 구독을 쓰려면 구독 계정과 로그인 계정이 맞는지 봅니다.

안내의 핵심 확인할 방향
Code Assist 조직의 사용자 자격이 필요함 조직 라이선스 배정 또는 불필요한 프로젝트 변수 영향
현재 위치에서 이용할 수 없음 해당 서비스의 현재 지원 지역·계정 조건
인자가 올바르지 않다는 인증 오류 계정 종류·필요한 Cloud 프로젝트·선택한 인증 경로

일반 개인 로그인은 대부분 프로젝트 없이 시작할 수 있지만, 회사·학교·Workspace나 특정 라이선스는 프로젝트가 필요할 수 있습니다. 계정 자격 문제를 네트워크 우회나 반복적인 새 계정 생성으로 해결할 수 있다고 보장하지 않습니다.

프로젝트·키 환경변수의 영향 확인하기

공식 오류 안내는 GOOGLE_CLOUD_PROJECT 또는 GOOGLE_CLOUD_PROJECT_ID가 설정되면 조직 자격 검사가 요구될 수 있다고 설명합니다. 다른 작업에서 설정한 값이 현재 CLI 세션에 영향을 주는지 확인하세요.

아래는 관련 변수의 값 대신 설정된 이름만 보는 예시입니다.

$cliVariableNames = @(
  'GEMINI_API_KEY',
  'GOOGLE_CLOUD_PROJECT',
  'GOOGLE_CLOUD_PROJECT_ID',
  'GOOGLE_CLOUD_LOCATION'
)
Get-ChildItem Env: |
  Where-Object { $_.Name -in $cliVariableNames } |
  Select-Object -ExpandProperty Name

개인 Google 로그인으로 연습 중이고 프로젝트 변수가 잘못 남은 것이 원인이라고 확인했다면, 해당 시험 PowerShell 세션에서만 두 변수를 제거해 다시 확인할 수 있습니다.

Remove-Item -LiteralPath Env:GOOGLE_CLOUD_PROJECT -ErrorAction SilentlyContinue
Remove-Item -LiteralPath Env:GOOGLE_CLOUD_PROJECT_ID -ErrorAction SilentlyContinue

이 명령은 현재 프로세스의 변수 조정이며 사용자·시스템의 영구 설정을 지우는 명령이 아닙니다. 조직 라이선스·Vertex AI에 필요한 프로젝트를 사용하는 경우에는 제거하는 대신 원래 프로젝트와 자격을 확인해야 합니다. .env·셸 설정·인증 캐시 전체를 무조건 삭제하지 않습니다.

429와 할당량 안내 확인하기

429라는 숫자만 보고 원인을 확정하지 마세요. 먼저 Google 로그인인지, API 키인지, Vertex AI인지와 오류가 나온 모델·프로젝트를 확인합니다.

CLI 안에서는 현재 사용량을 확인할 수 있습니다.

/stats model

Google 로그인 계열의 한도는 사용자 질문 횟수와 같지 않습니다. 도구를 거치는 한 요청이 여러 모델 호출로 이어질 수 있고, Code Assist agent mode와 CLI 사용이 합쳐지는 조건도 있습니다. 인증별 한도에서 현재 경로를 대조하세요.

API 키 경로는 분당 요청·입력 토큰·일일 요청 등 모델/프로젝트별 제한을 확인해야 합니다. 키만 새로 만든다고 같은 프로젝트의 한도가 새로 생기는 것은 아닙니다. Gemini API 공식 문서는 429·일부 일시 오류에서 재시도 간격을 늘리는 방식을 안내합니다. 같은 요청을 짧은 간격으로 계속 보내기보다 제한·재개 안내부터 확인하세요.

일일 한도가 소진된 상황과 일시적인 요청률·서비스 가용성 문제를 구분해야 합니다. 모델을 바꾸거나 구독하면 모든 429가 사라진다고 보장하지 않습니다. 현재 상태·오류 안내와 해당 인증 경로의 공식 지원을 함께 봅니다.

인증서·프록시 오류 확인하기

UNABLE_TO_GET_ISSUER_CERT_LOCALLY 같은 문구는 기업 네트워크의 인증서 검사나 Node의 인증서 신뢰 설정과 관련될 수 있습니다. 브라우저에서 접속된다고 Node의 연결도 같은 조건으로 성공하는 것은 아닙니다.

공식 CLI 오류 문서는 NODE_USE_SYSTEM_CA와 NODE_EXTRA_CA_CERTS 경로를 안내합니다. 관리되는 PC라면 조직이 배포한 인증서를 Node가 올바르게 신뢰하도록 관리자와 확인하세요. 출처를 확인하지 않은 인증서를 추가하거나 TLS 검증을 끄는 방식으로 우회하지 않습니다.

MCP 문제와 일반 CLI 문제 구분하기

CLI 대화는 되는데 MCP만 실패한다면, 서버 명령·파일 경로·런타임·프로젝트 설정·서버 인증부터 봅니다. 설정이 읽혀도 서버가 시작되지 않을 수 있고, 연결돼도 허용한 도구가 없을 수 있습니다.

/mcp list로 현재 서버·도구 상태를 확인하고 MCP 가이드에서 단계별로 점검하세요. 서버 항목을 지우는 것과 외부 서비스의 키·권한을 회수하는 것은 다릅니다.

참고자료