Gemini CLI 인증 설정

Gemini CLI를 사용하려면 Google 인증이 필요합니다. 이 가이드는 계정 유형과 CLI 사용 방식에 따라 가장 적합한 로그인 방법을 빠르게 찾을 수 있도록 도와줍니다.

대부분의 사용자에게는 Gemini CLI를 시작하고 개인 Google 계정으로 로그인하는 것을 권장합니다.

인증 방법 선택

아래 표에서 상황에 맞는 인증 방법을 선택하세요.

사용자 유형 / 시나리오	권장 인증 방법	Google Cloud 프로젝트 필요 여부
개인 Google 계정	Google 로그인	아니요 (예외 있음)
회사, 학교 또는 Google Workspace 계정을 사용하는 조직 사용자	Google 로그인	예
Gemini API 키를 가진 AI Studio 사용자	Gemini API 키 사용	아니요
Google Cloud Vertex AI 사용자	Vertex AI	예
헤드리스 모드	Gemini API 키 사용 또는 Vertex AI	아니요 (Gemini API 키의 경우) 예 (Vertex AI의 경우)

내 Google 계정 유형은 무엇인가요?

개인 Google 계정: 개인용 Gemini Code Assist와 같은 모든 무료 계정과 Google AI Pro 및 Ultra (opens in a new tab) 유료 구독이 포함됩니다.
조직 계정: 회사, 학교 또는 Google Workspace (opens in a new tab)와 같은 조직을 통해 유료 라이선스를 사용하는 계정입니다. Google AI Ultra for Business (opens in a new tab) 구독이 포함됩니다.

(권장) Google 로그인

로컬 머신에서 Gemini CLI를 실행하는 경우 가장 간단한 인증 방법은 Google 계정으로 로그인하는 것입니다. 이 방법을 사용하려면 Gemini CLI를 실행하는 터미널과 통신할 수 있는 머신(예: 로컬 머신)에 웹 브라우저가 필요합니다.

중요: Google AI Pro 또는 Google AI Ultra 구독자인 경우 구독과 연결된 Google 계정을 사용하세요.

Gemini CLI를 인증하고 사용하려면 다음 단계를 따르세요.

CLI 시작:
```
gemini
```
Login with Google을 선택합니다. Gemini CLI가 웹 브라우저를 사용하여 로그인 프롬프트를 엽니다. 화면의 지시에 따르세요. 자격 증명은 향후 세션을 위해 로컬에 캐시됩니다.

Google Cloud 프로젝트를 설정해야 하나요?

대부분의 개인 Google 계정(무료 및 유료)은 인증을 위해 Google Cloud 프로젝트가 필요하지 않습니다. 그러나 다음 조건 중 하나 이상을 충족하는 경우 Google Cloud 프로젝트를 설정해야 합니다.

회사, 학교 또는 Google Workspace 계정을 사용 중입니다.
Google Developer Program의 Gemini Code Assist 라이선스를 사용 중입니다.
Gemini Code Assist 구독 라이선스를 사용 중입니다.

자세한 지침은 Google Cloud 프로젝트 설정을 참조하세요.

Gemini API 키 사용

Google 계정을 사용하여 인증하지 않으려면 Google AI Studio에서 API 키를 사용할 수 있습니다.

Gemini API 키로 Gemini CLI를 인증하고 사용하려면 다음을 수행하세요.

Google AI Studio (opens in a new tab)에서 API 키를 발급받습니다.
GEMINI_API_KEY 환경 변수를 키로 설정합니다. 예:
```
# YOUR_GEMINI_API_KEY를 AI Studio의 키로 교체하세요
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
```
이 설정을 영구적으로 유지하려면 환경 변수 유지를 참조하세요.
CLI 시작:
```
gemini
```
Use Gemini API key를 선택합니다.

경고: 특히 Gemini와 같은 서비스의 API 키는 민감한 자격 증명으로 취급하세요. 무단 액세스 및 계정 서비스의 오용을 방지하려면 키를 보호해야 합니다.

Use Vertex AI

To use Gemini CLI with Google Cloud's Vertex AI platform, choose from the following authentication options:

A. Application Default Credentials (ADC) using gcloud.
B. Service account JSON key.
C. Google Cloud API key.

Regardless of your authentication method for Vertex AI, you'll need to set GOOGLE_CLOUD_PROJECT to your Google Cloud project ID with the Vertex AI API enabled, and GOOGLE_CLOUD_LOCATION to the location of your Vertex AI resources or the location where you want to run your jobs.

For example:

# Replace with your project ID and desired location (e.g., us-central1)
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"

Vertex AI 환경 변수 설정을 영구적으로 유지하려면 환경 변수 유지를 참조하세요.

A. Vertex AI - `gcloud`를 사용하는 애플리케이션 기본 자격 증명 (ADC)

Google Cloud CLI가 설치되어 있는 경우 이 인증 방법을 고려해 보세요.

참고: GOOGLE_API_KEY 또는 GEMINI_API_KEY를 이전에 설정한 경우 ADC를 사용하려면 설정을 해제해야 합니다.
unset GOOGLE_API_KEY GEMINI_API_KEY

Google Cloud 프로젝트가 있고 Vertex AI API가 활성화되어 있는지 확인합니다.
Google Cloud에 로그인합니다:
```
gcloud auth application-default login
```
Google Cloud 프로젝트 구성을 수행합니다.
CLI 시작:
```
gemini
```
Vertex AI를 선택합니다.

B. Vertex AI - 서비스 계정 JSON 키

비대화형 환경, CI/CD 파이프라인에서 또는 조직이 사용자 기반 ADC 또는 API 키 생성을 제한하는 경우 이 인증 방법을 고려해 보세요.

참고: GOOGLE_API_KEY 또는 GEMINI_API_KEY를 이전에 설정한 경우 설정을 해제해야 합니다.
unset GOOGLE_API_KEY GEMINI_API_KEY

서비스 계정 및 키 생성 (opens in a new tab)을 수행하고 제공된 JSON 파일을 다운로드합니다. 서비스 계정에 "Vertex AI User" 역할을 할당합니다.

GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 JSON 파일의 절대 경로로 설정합니다. 예:

# /path/to/your/keyfile.json을 실제 경로로 교체하세요
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"

Google Cloud 프로젝트 구성을 수행합니다.
CLI 시작:
```
gemini
```
Vertex AI를 선택합니다.

경고: 리소스에 대한 액세스 권한을 제공하므로 서비스 계정 키 파일을 보호하세요.

C. Vertex AI - Google Cloud API 키

Google Cloud API 키를 얻습니다: API 키 가져오기 (opens in a new tab).
GOOGLE_API_KEY 환경 변수를 설정합니다:
```
# YOUR_GOOGLE_API_KEY를 Vertex AI API 키로 교체하세요
export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
```
참고: "API keys are not supported by this API..."와 같은 오류가 표시되면 조직이 이 서비스에 대한 API 키 사용을 제한할 수 있습니다. 대신 다른 Vertex AI 인증 방법을 시도해 보세요.
Google Cloud 프로젝트 구성을 수행합니다.
CLI 시작:
```
gemini
```
Vertex AI를 선택합니다.

Google Cloud 프로젝트 설정

중요: 대부분의 개인 Google 계정(무료 및 유료)은 인증을 위해 Google Cloud 프로젝트가 필요하지 않습니다.

Google 계정을 사용하여 로그인할 때 Gemini CLI가 사용할 Google Cloud 프로젝트를 구성해야 할 수 있습니다. 다음 조건 중 하나 이상을 충족하는 경우에 해당합니다.

회사, 학교 또는 Google Workspace 계정을 사용 중입니다.
Google Developer Program의 Gemini Code Assist 라이선스를 사용 중입니다.
Gemini Code Assist 구독 라이선스를 사용 중입니다.

Gemini CLI가 Google Cloud 프로젝트를 사용하도록 구성하려면 다음을 수행하세요.

Google Cloud 프로젝트 ID 찾기 (opens in a new tab).
Gemini for Cloud API 활성화 (opens in a new tab).
필요한 IAM 액세스 권한 구성 (opens in a new tab).
환경 변수를 구성합니다. GOOGLE_CLOUD_PROJECT 또는 GOOGLE_CLOUD_PROJECT_ID 변수를 Gemini CLI와 함께 사용할 프로젝트 ID로 설정합니다. Gemini CLI는 GOOGLE_CLOUD_PROJECT를 먼저 확인한 다음 GOOGLE_CLOUD_PROJECT_ID로 대체합니다.

예를 들어 GOOGLE_CLOUD_PROJECT_ID 변수를 설정하려면 다음과 같이 합니다:
```
# YOUR_PROJECT_ID를 실제 Google Cloud 프로젝트 ID로 교체하세요
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
```
이 설정을 영구적으로 유지하려면 환경 변수 유지를 참조하세요.

환경 변수 유지

모든 터미널 세션마다 환경 변수를 설정하지 않으려면 다음 방법으로 영구적으로 유지할 수 있습니다.

셸 구성 파일에 환경 변수 추가: 셸의 시작 파일(예: ~/.bashrc, ~/.zshrc 또는 ~/.profile)에 export ... 명령을 추가하고 셸을 다시 로드(예: source ~/.bashrc)합니다.
```
# .bashrc 예시
echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
source ~/.bashrc
```
경고: 셸 구성 파일에서 API 키나 서비스 계정 경로를 내보내면 해당 셸에서 시작된 모든 프로세스가 이를 읽을 수 있다는 점에 유의하세요.
.env 파일 사용: 프로젝트 디렉터리나 홈 디렉터리에 .gemini/.env 파일을 만듭니다. Gemini CLI는 현재 디렉터리에서 시작하여 상위 디렉터리, 그리고 ~/.gemini/.env 또는 ~/.env에서 발견되는 첫 번째 .env 파일에서 변수를 자동으로 로드합니다. .gemini/.env를 사용하는 것이 좋습니다.

사용자별 설정 예시:
```
mkdir -p ~/.gemini
cat >> ~/.gemini/.env <<'EOF'
GOOGLE_CLOUD_PROJECT="your-project-id"
# GEMINI_API_KEY와 같은 다른 변수도 필요에 따라 추가하세요
EOF
```

변수는 발견된 첫 번째 파일에서만 로드되며 병합되지 않습니다.

Google Cloud 환경에서 실행

특정 Google Cloud 환경에서 Gemini CLI를 실행할 때 인증은 자동으로 수행됩니다.

Google Cloud Shell 환경에서 Gemini CLI는 일반적으로 Cloud Shell 자격 증명을 사용하여 자동으로 인증합니다. Compute Engine 환경에서 Gemini CLI는 환경의 메타데이터 서버에서 애플리케이션 기본 자격 증명(ADC)을 자동으로 사용합니다.

자동 인증이 실패하면 이 페이지에 설명된 대화형 방법 중 하나를 사용하세요.

헤드리스 모드에서 실행

헤드리스 모드는 기존 인증 자격 증명이 캐시된 경우 기존 인증 방법을 사용합니다.

인증 자격 증명으로 아직 로그인하지 않은 경우 환경 변수를 사용하여 인증을 구성해야 합니다.

다음 단계

인증 방법은 할당량, 가격 책정, 서비스 약관 및 개인정보처리방침에 영향을 미칩니다. 자세한 내용은 다음 페이지를 검토하세요.

설치 예제