Gemini CLI에서 API 키와 중계 서비스 Base URL을 설정하는 방법

Gemini CLI란

Gemini CLI는 터미널에서 채팅, 코드 설명, 파일 분석, 개발 보조를 하는 Google의 명령줄 AI 도구입니다. Claude Code나 Codex의 복제가 아니며, 인증, 환경 변수, 모델 라우팅이 다릅니다.

이 가이드는 중계 서비스 이용자에게 중요한 두 경로만 다룹니다.

• Login with Google: Google 계정을 씁니다. 공식 CLI를 먼저 써 보기 좋습니다.
• Gemini API Key (AI Studio): GEMINI_API_KEY를 씁니다. 대부분의 중계 가이드가 기대하는 경로입니다.

많은 “Gemini CLI 프록시” 서비스는 실제로 Google 또는 Gemini 모델을 노출하는 멀티 모델 API 집계기입니다. 이것이 곧바로 네이티브 Gemini CLI 호환을 뜻하지는 않습니다.

처음부터 전역 설정을 바꾸지 마세요. Google 또는 Gemini 모델을 분명히 적어 둔 서비스를 고르고, 임시 키나 적은 크레딧으로 작은 시험을 한 뒤에야 일상 코딩에 넣을지 결정하세요.

아직 서비스를 비교 중이면 AI API 중계 서비스에서 Google 또는 Gemini 모델을 제공하는 서비스를 확인하세요.

Gemini CLI 설치

먼저 Node.js를 확인하세요. Gemini CLI는 Node.js 20 이상을 써야 합니다.

node --version

공식 npm 설치 경로는 다음과 같습니다.

npm install -g @google/gemini-cli
gemini --version

전역 설치 없이 임시로 실행하려면 다음도 가능합니다.

npx @google/gemini-cli

설치 후 한 번 시작합니다.

gemini

설치 후 쓰기 쉽게 만들기

짧은 명령 별칭 추가

매번 gemini를 치기 길다면 셸 별칭을 추가하세요. g 대신 gm을 권합니다. g는 git 별칭, 디렉터리 점프 도구, 다른 로컬 단축키와 자주 충돌합니다.

macOS / Linux에서 Bash 또는 Zsh를 쓰면 셸 프로필에 별칭을 넣습니다.

# Zsh usually uses ~/.zshrc; Bash usually uses ~/.bashrc or ~/.bash_profile
echo 'alias gm="gemini"' >> ~/.zshrc
source ~/.zshrc

그다음 Gemini CLI를 이렇게 시작합니다.

gm

Windows PowerShell에서는 $PROFILE을 엽니다.

notepad $PROFILE

그리고 다음을 추가합니다.

Set-Alias gm gemini

참고: 이 별칭은 Gemini CLI가 시작되기 전에 터미널에서 gm을 gemini로 펼칠 뿐입니다. Gemini CLI 내부 별칭이 아니며, 프로필의 셸 별칭은 Gemini CLI 셸 명령 안에서는 동작하지 않을 수 있습니다.

인증 경로 고르기

첫 실행에서는 Login with Google과 Gemini API Key에 집중하세요. 규칙은 단순합니다.

• 공식 Gemini CLI만 써 보고 싶다: Login with Google을 고릅니다. Google 로그인 페이지를 열 수 있는 개인 이용자에게 맞습니다.
• 중계 서비스나 API 키를 쓰고 싶다: Gemini API Key (AI Studio)를 고릅니다. 대부분의 중계 설정 가이드가 기대하는 경로입니다.

한 번 시작합니다.

gemini

나중에 인증을 바꾸려면 Gemini CLI 안에서 다음을 실행합니다.

/auth

그리고 맞는 항목을 고릅니다.

○ Login with Google
● Gemini API Key (AI Studio)

대부분의 중계 설정에서는 Gemini API Key (AI Studio)를 고르고, Gemini CLI가 터미널 환경에서 GEMINI_API_KEY를 읽게 합니다.

API 키와 중계 엔드포인트 설정

공식 AI Studio API 키의 최소 설정은 다음과 같습니다.

export GEMINI_API_KEY="your Gemini API key"
gemini

중계 서비스에서는 많은 가이드가 API 키와 중계 엔드포인트를 함께 설정하라고 합니다.

export GEMINI_API_KEY="your proxy API key"
export GOOGLE_GEMINI_BASE_URL="https://your-proxy.example"
gemini

오래 쓸 때는 이 값을 셸 프로필에 넣으세요. Zsh 사용자는 보통 ~/.zshrc를 고칩니다.

nano ~/.zshrc

다음을 추가합니다.

export GEMINI_API_KEY="your proxy API key"
export GOOGLE_GEMINI_BASE_URL="https://your-proxy.example"

프로필을 다시 읽습니다.

source ~/.zshrc

Bash 사용자는 보통 ~/.bashrc를 고칩니다.

nano ~/.bashrc
source ~/.bashrc

Windows CMD는 임시 변수를 이렇게 설정할 수 있습니다.

set GEMINI_API_KEY=your proxy API key
set GOOGLE_GEMINI_BASE_URL=https://your-proxy.example

PowerShell은 다음을 씁니다.

$env:GEMINI_API_KEY="your proxy API key"
$env:GOOGLE_GEMINI_BASE_URL="https://your-proxy.example"

참고: GOOGLE_GEMINI_BASE_URL 지원 여부와 URL에 경로 접미사가 필요한지는 서비스마다 다릅니다. 다른 서비스의 엔드포인트를 그대로 복사하지 마세요.

흔한 실행 패턴

설정 후 다음 패턴을 씁니다.

# Interactive mode
gm

# Ask one direct question
gemini "Explain this project's directory structure"

# Test a specific model; use the model name from your provider docs
gemini -m gemini-2.5-flash "Introduce Gemini CLI in one sentence"

설치 후 동작 확인

깨끗한 터미널을 쓰고 먼저 이전 변수를 지웁니다.

unset GEMINI_API_KEY GOOGLE_API_KEY
export GEMINI_API_KEY="provider or official test key"
gemini

서비스가 커스텀 Base URL을 요구하면 서비스가 준 엔드포인트를 추가합니다.

export GOOGLE_GEMINI_BASE_URL="https://your-proxy.example"
gemini "Explain in one sentence which model you are connected to"

기본 채팅이 되면 다음 네 가지를 작게 확인합니다.

1. gemini -p "Explain this codebase architecture"가 정상으로 돌아옵니다.
2. gemini -m gemini-2.5-flash "hello"가 특정 모델에서 동작합니다.
3. 프로젝트 안에서 gemini를 시작하고 작은 파일을 읽어 달라고 합니다.
4. 위험이 낮은 코드 설명 또는 생성 작업을 하나 실행해 스트리밍, 도구 동작, 모델 이름을 확인합니다.

평범한 답변은 기본 요청이 된다는 것만 증명합니다. 코드 읽기, 파일 수정, 스트리밍 동작, 모델 이름은 계속 시험하세요. 서비스 문서에 Gemini CLI가 없다면, 네이티브 Gemini CLI를 지원하는지, OpenAI 호환 엔드포인트로 Gemini 모델만 제공하는지 물어보세요.

중계 서비스에 물어볼 것

보통 먼저 두 가지를 봅니다. 문서에 GEMINI_API_KEY가 있는지, GOOGLE_GEMINI_BASE_URL이 있는지입니다. 첫 실행에서 인증 선택 화면이 나오면, 가이드가 /auth에서 Gemini API Key (AI Studio)를 고르라고 하는지 확인하세요.

서비스가 Gemini 모델만 나열하거나 “OpenAI 호환”이라고만 하면, 아직 Gemini CLI 호환으로 보지 마세요. Gemini CLI의 파일 읽기, 스트리밍, 도구 동작 없이 OpenAI 호환 엔드포인트로 Gemini만 노출할 수 있습니다.

문서가 불명확하면 적은 잔액으로만 시험하세요. 지원 창구가 변수 이름, Base URL, /auth 선택을 설명하지 못하면 미검증으로 남겨 두세요.

흔한 오류

• 401 / unauthorized: 키 종류가 다르거나, 서비스가 Gemini CLI가 보내는 인증 형식을 받지 않습니다.
• 403 / permission denied: 키 인증은 되지만 계정, 프로젝트, 모델 권한이 없습니다.
• 404 / not found: Base URL 경로가 틀립니다. 보통 /v1이 필요한지와 관련됩니다.
• model not found: 모델 별칭이 서비스에 적힌 모델 이름과 맞지 않습니다.
• 429 / too many requests: 쓸 수 있는 한도가 없거나, 속도 제한에 걸렸거나, CLI / 코딩 에이전트가 너무 자주 재시도합니다.
• network error / timeout: 로컬 네트워크, 프록시, 서비스 측, 또는 업스트림 타임아웃입니다.
• 채팅은 되지만 코딩 도구가 실패: 서비스가 일반 완성은 지원해도 Gemini CLI가 필요로 하는 도구 호출이나 스트리밍은 지원하지 않을 수 있습니다.

401 또는 429가 나면 먼저 서비스를 바꾸지 마세요. 아래 관련 오류 페이지를 열고 Base URL, API 키, 모델 이름, 잔액, 속도 제한 순으로 확인하세요.

설정을 쉽게 하는 도구

중계 엔드포인트를 하나만 연결한다면 ~/.zshrc를 직접 고치는 것으로 충분합니다. 서비스를 자주 바꿀 때 도구가 도움이 됩니다.

CC Switch 같은 구성 관리자는 프로바이더 프로필, Base URL, API 키, 모델 이름, Claude Code, Codex, Gemini CLI, OpenCode의 사용량 추적을 관리하는 데 도움이 됩니다.

순서가 중요합니다. 먼저 최소 설정을 직접 시험하고, 동작하는 설정을 도구에 저장하세요. 그렇지 않으면 도구는 깨진 설정을 더 빨리 정리하는 데만 도움이 됩니다.

다음 단계

쓸모 있는 Gemini CLI 중계 페이지는 “Gemini 지원”만 적으면 안 됩니다. 서비스가 Google 또는 Gemini 모델, 요금, 결제 방법, Gemini CLI 설정 메모를 공개하는지 보여 줘야 합니다. 모델 목록은 후보에 넣는 기준이고, 안정적인 CLI 동작이 실제 기준입니다.