Google의 Gemini CLI를 Windows 환경에서 성공적으로 설치하고 사용하려면 Node.js 설치부터 시작해야 합니다. 이 가이드는 초보자도 쉽게 따라할 수 있도록 단계별로 구성되어 있으며, 2024-2025년 최신 정보를 기반으로 합니다.
1단계: Node.js 최신 버전 설치 (필수 선행 작업)
시스템 요구사항 확인
Windows 7, 8, 10, 11에서 모두 작동하며, Node.js 18 이상(권장: 20 이상)이 필요합니다. 현재 최신 LTS 버전은 **v22.17.1 "Jod"**입니다.
Windows에서 Node.js 설치하기
1. 공식 웹사이트에서 다운로드
- https://nodejs.org/en/download 접속
- "Windows Installer" 버튼 클릭하여 LTS 버전 다운로드
.msi파일이 다운로드됩니다 (보통 다운로드 폴더에 저장)
nodejs.org
image.png클릭하여 확대
다운로드
image.png클릭하여 확대
2. 설치 프로그램 실행
1. 다운로드된 .msi 파일을 더블클릭
2. "다음" 버튼을 클릭하여 진행
3. 라이선스 동의 후 "다음" 클릭
4. 설치 경로는 기본값(C:\Program Files\nodejs\) 유지 권장
5. 구성 요소 선택에서 중요한 옵션들:
✓ Node.js runtime (기본 선택됨)
✓ npm package manager (기본 선택됨)
✓ Add to PATH (반드시 체크되어 있어야 함)
6. "설치" 클릭
7. 관리자 권한 요청 시 "예" 클릭
8. "완료" 클릭
3. 설치 확인 명령 프롬프트(cmd)를 열고 다음 명령어를 실행:
node -v
npm -v
두 명령어 모두 버전 번호가 출력되면 설치 성공입니다.
image.png클릭하여 확대
2단계: Gemini CLI 설치
기본 설치 방법
전역 설치 (권장):
npm install -g @google/gemini-cli
image.png클릭하여 확대
설치 확인
gemini --version
where gemini
image.png클릭하여 확대
버전 정보와 설치 경로가 출력되면 설치가 완료된 것입니다.
3단계: 명령 프롬프트에서 Gemini CLI 사용하기
기본 사용법
CLI 시작:
gemini
image.png클릭하여 확대
image.png클릭하여 확대
image.png클릭하여 확대
인증성공
image.png클릭하여 확대
직접 프롬프트 실행:
gemini "안녕하세요, 테스트입니다"
주요 명령어들
도움말 및 정보:
gemini --help # 도움말 표시
gemini --version # 버전 정보
대화형 모드에서 사용할 수 있는 슬래시 명령어:
/help # 사용 가능한 명령어 표시
/tools # 내장 도구 목록
/stats # 세션 통계
/exit # CLI 종료
/quit # CLI 종료
/theme # 색상 테마 변경
4단계: API 키 설정 방법
Google AI Studio에서 API 키 발급
1. Google AI Studio 접속
- https://aistudio.google.com/app/apikey 방문
- Google 계정으로 로그인
2. API 키 생성
1. 왼쪽 메뉴에서 "Get API Key" 클릭
2. "Create API Key" 버튼 클릭
3. "Create API key in new project" 선택 (신규 사용자)
4. 생성된 API 키를 안전한 곳에 복사해서 저장
Windows 환경 변수 설정
방법 1: 시스템 속성을 통한 설정 (권장)
1. Windows + R 키를 누르고 sysdm.cpl 입력 후 엔터
2. "고급" 탭 클릭
3. "환경 변수" 버튼 클릭
4. 사용자 변수에서 "새로 만들기" 클릭
5. 변수 이름: GEMINI_API_KEY
6. 변수 값: 발급받은 API 키 입력
7. "확인" 클릭하여 저장
8. 명령 프롬프트를 다시 시작
방법 2: 명령어를 통한 설정
# 현재 사용자만
setx GEMINI_API_KEY "your_api_key_here"
# 시스템 전체 (관리자 권한 필요)
setx GEMINI_API_KEY "your_api_key_here" /m
설정 확인:
echo %GEMINI_API_KEY%
5단계: 간단한 테스트 예제 및 실행
기본 테스트
1. 설치 확인 테스트
gemini
> 안녕하세요, 테스트입니다
2. 파일 작업 테스트
gemini
> 간단한 hello.txt 파일을 만들어 주세요
3. 코드 생성 테스트
gemini
> 원의 넓이를 계산하는 Python 함수를 작성해 주세요
실용적인 사용 예제
파일 분석:
cd C:\내프로젝트
gemini
> @파일명.py
> 이 파일의 코드를 설명해 주세요
시스템 명령어 실행:
gemini
> !dir # 디렉토리 목록 표시
> !echo %PATH% # PATH 환경변수 표시
프로젝트 작업:
> 이 프로젝트의 README.md 파일을 작성해 주세요
> 모든 .js 파일을 분석하고 코드 구조를 설명해 주세요
배치 파일을 통한 빠른 테스트
다음 내용으로 test_gemini.bat 파일을 만들어 테스트할 수 있습니다:
@echo off
echo Gemini CLI 설치 테스트 중...
echo 1. Node.js 확인...
node -v
echo 2. npm 확인...
npm -v
echo 3. Gemini CLI 설치 확인...
gemini --version
echo 4. 환경 변수 확인...
echo %GEMINI_API_KEY%
echo 테스트 완료! gemini 명령어로 시작하세요.
pause
6단계: Windows 환경 문제 해결 방법
가장 일반적인 문제들
1. "'gemini'이(가) 내부 또는 외부 명령이 아닙니다" 오류
이는 가장 흔한 문제로 PATH 환경변수 설정 오류입니다.
해결 방법:
# npm 전역 디렉토리 확인
npm config get prefix
# PATH에 npm 디렉토리 추가
setx PATH "%PATH%;%AppData%\npm"
# 명령 프롬프트를 다시 시작 후 테스트
gemini --version
2. PowerShell 실행 정책 오류
오류 메시지: npm.ps1을 로드할 수 없습니다
해결 방법:
# PowerShell을 관리자 권한으로 실행
Set-ExecutionPolicy RemoteSigned
# Y를 입력하여 확인
3. 권한 관련 EPERM 오류
해결 방법:
- 명령 프롬프트를 관리자 권한으로 실행
- 또는 nvm-windows 사용 권장
4. 회사 방화벽/프록시 문제
해결 방법:
# 프록시 설정
npm config set proxy [http://username:password@proxy-server:port](http://username:password@proxy-server:port)
npm config set https-proxy [http://username:password@proxy-server:port](http://username:password@proxy-server:port)
npm config set registry [http://registry.npmjs.org/](http://registry.npmjs.org/)
5. API 키 인식 문제
해결 방법:
# 환경 변수 재설정
setx GEMINI_API_KEY "your_key_here"
# 또는 .env 파일 생성
echo GEMINI_API_KEY=your_key_here > .env
단계별 문제 진단 방법
1. 기본 설치 확인:
node -v
npm -v
gemini --version
2. PATH 확인:
echo %PATH%
where gemini
3. npm 설정 확인:
npm config get prefix
npm list -g @google/gemini-cli
4. 권한 테스트:
# 관리자 권한으로 명령 프롬프트 실행 후
npm install -g @google/gemini-cli
완전한 재설치 방법
문제가 계속 발생할 경우:
# 1. 기존 설치 제거
npm uninstall -g @google/gemini-cli
# 2. npm 캐시 정리
npm cache clean --force
# 3. 재설치
npm install -g @google/gemini-cli
# 4. 확인
gemini --version
성공적인 설치를 위한 최종 체크리스트
- Node.js LTS 버전 설치 완료
-
node -v및npm -v명령어 작동 - Gemini CLI 전역 설치 완료
-
gemini --version명령어 작동 - API 키 환경 변수 설정 완료
-
echo %GEMINI_API_KEY%확인 - 간단한 테스트 대화 성공
- 파일 작업 테스트 성공