3일 만에 설정 하나 때문에 이렇게 고생할 줄 몰랐다. Claude Code(커뮤니티에서 OpenClaw라고도 불린다)에 Google Gemini CLI를 연결하면 하루 1,500 요청 무료 티어와 최대 100만 토큰 컨텍스트 윈도우를 추가 비용 없이 쓸 수 있다. 설정 자체는 15분이면 끝난다 — 지금 돌아보면. 처음엔 Vertex AI와 Google AI Studio 키를 혼동하고, 모델명 형식도 잘못 입력하면서 꼬박 3일을 날렸다. 그때 막혔던 부분과 해결법을 아래에 정리해 뒀다.
왜 Google Gemini CLI를 Claude Code에 연결할까?
기본 Claude Code는 Anthropic Claude 모델만 사용하지만, 외부 모델 프로바이더 설정이 가능하다. Google Gemini CLI를 붙이면 아래 표처럼 달라진다:
| 항목 | Claude 단독 | Gemini 연결 후 |
|---|---|---|
| 컨텍스트 윈도우 | 200K 토큰 | 최대 1M 토큰 |
| 무료 사용량 | 없음 (유료) | Gemini 2.0 Flash 기준 1,500 요청/일 |
| 멀티모달 | 이미지 지원 | 이미지 + 동영상 + 오디오 |
| Google 서비스 연동 | 제한적 | Google Drive·Docs 직접 참조 |
Google AI Studio 무료 티어 공식 문서에 따르면 Gemini 2.0 Flash는 분당 15 요청, 하루 1,500 요청이 무료다. 반복적인 리팩터링이나 코드 리뷰처럼 요청이 많은 작업에서 Claude API 크레딧 소모를 크게 줄일 수 있다.
연결 방법 — 4단계 설치 가이드
Step 1 — Google Gemini CLI 설치
npm install -g @google/gemini-cli
설치 확인:
gemini --version
Step 2 — API 키 발급 (여기서 많이 막힘)
Google AI Studio에서 API 키를 발급한다. Vertex AI 서비스 계정 키와 완전히 다르다 — 이 차이를 몰라서 2시간을 날렸다.
- Google AI Studio 키 → 개인 프로젝트용, 무료 티어 포함, 발급 1분
- Vertex AI 서비스 계정 → GCP 엔터프라이즈 환경용, JSON 파일 방식
export GEMINI_API_KEY="AIza..."
영구 등록 (zsh 기준):
echo 'export GEMINI_API_KEY="AIza..."' >> ~/.zshrc
source ~/.zshrc
Step 3 — Claude Code 설정 파일 수정
설정 파일 경로: ~/.claude/settings.json
{
"model": "gemini-2.0-flash",
"apiProvider": "google",
"apiKey": "AIza..."
}
주의: 이 파일이 없는 경우가 많다.
mkdir -p ~/.claude && touch ~/.claude/settings.json으로 직접 생성하면 된다.
Step 4 — 연결 테스트
claude "지금 어떤 모델이 연결되어 있어?"
Gemini 모델명이 응답에 포함되면 성공이다.
3일 날린 진짜 원인 4가지
1. Vertex AI vs Google AI Studio 키 혼동 (2시간 손실)
Gemini 관련 문서를 검색하면 Vertex AI 가이드가 상위에 잡힌다. Vertex AI는 GOOGLE_APPLICATION_CREDENTIALS 환경변수에 서비스 계정 JSON 파일 경로를 넣는 방식인데, Claude Code는 이 인증 방식을 인식하지 못한다. Google AI Studio에서 단순 문자열 API 키를 받아 GEMINI_API_KEY로 설정해야 한다. 처음엔 GCP 콘솔에서 서비스 계정을 만들고 JSON을 다운받아 경로를 넣었는데 계속 인증 에러만 떴다.
2. 모델명 형식 에러 (1시간 손실)
Google 공식 API 문서에는 models/gemini-2.0-flash 형식을 쓰는데, Claude Code 설정에 이 형식으로 넣으면 에러가 난다.
| 입력 형식 | 결과 |
|---|---|
models/gemini-2.0-flash | ❌ 에러 |
gemini/gemini-2.0-flash | ❌ 에러 |
gemini-2.0-flash | ✅ 정상 |
앞에 아무것도 붙이지 말고 모델명만 쓰면 된다. 문서마다 형식이 달라서 어디에 맞춰야 할지 한참 헤맸다.
3. 환경변수가 세션마다 초기화 (30분 손실)
export GEMINI_API_KEY="..." 명령어를 실행한 뒤 새 터미널을 열면 연결이 끊기는 현상이 반복됐다. export는 현재 쉘 세션에만 적용된다. .zshrc에 영구 등록하고 source ~/.zshrc를 실행해야 한다. macOS Catalina 이후 기본 쉘이 zsh로 바뀌었으므로 .bashrc에만 등록하면 적용이 안 된다. 알고 보면 당연한 건데 처음엔 몰라서 매번 다시 export를 입력했다.
4. 무료 티어 Rate Limit의 현실 (계속되는 문제)
Gemini 2.0 Flash 무료 티어는 분당 15 요청 제한이 있다. 큰 코드베이스를 연속으로 분석하다 보면 429 RESOURCE_EXHAUSTED 에러가 자주 뜬다. 그나마 통한 방법:
- 요청 사이에 5초 이상 간격 두기
- 무거운 작업은 청크 단위로 나눠서 요청
- 빠른 응답이 필요한 경우는 Claude 기본값 유지하고, 장시간 대용량 분석 작업에만 Gemini 활용
연결 후 3주간 실제 변화
- API 비용: 반복 리팩터링·코드 리뷰 작업에 Gemini Free Tier를 활용해 월 Claude API 비용이 약 40% 줄었다
- 긴 파일 분석: 5,000줄 이상 파일을 통째로 넘겨도 잘리지 않고 전체 분석이 됐다 (Claude 200K 한도 초과 시 유용)
- 워크플로우 분리: Claude는 복잡한 설계 문제, Gemini는 대용량 파일 분석으로 역할을 나눠 쓰는 게 가장 효율적이었다
FAQ
Q1. Gemini API 키는 유료인가요?
Google AI Studio에서 발급하는 API 키는 기본적으로 무료다. Gemini 2.0 Flash 기준 하루 1,500 요청, 분당 15 요청까지 무료이며, 초과 시 $0.075 / 100만 토큰 요금이 청구된다. 공식 요금 표 참조.
Q2. Claude Code와 Gemini CLI를 필요에 따라 골라 쓸 수 있나요?
가능하다. settings.json에 기본 모델을 설정해도, 실행 시 --model 플래그로 override할 수 있다. 예: claude --model claude-opus-4-5 "복잡한 설계 검토". 복잡도가 높은 작업만 Claude, 반복·대용량 작업은 Gemini로 분리해서 쓰면 이 조합이 지갑에 제일 덜 아팠다.
Q3. ~/.claude/settings.json 파일이 없으면 어떻게 하나요?
터미널에서 mkdir -p ~/.claude && echo '{}' > ~/.claude/settings.json 을 실행하면 빈 설정 파일이 생성된다. 이후 텍스트 에디터로 열어 필요한 키를 추가하면 된다.
Q4. Windows에서도 동일하게 설정할 수 있나요?
환경변수 설정 방식이 다르다. Windows PowerShell에서는 $env:GEMINI_API_KEY="AIza..." 로 임시 설정하고, 영구 등록은 시스템 환경변수 UI에서 추가해야 한다. 설정 파일 경로는 %USERPROFILE%\.claude\settings.json 이다.