Claude Code CLI에 구글 Gemini 연동하기

개발자들 사이에서 터미널 기반 AI 코딩 에이전트인 Claude Code CLI의 활용도가 높아지고 있습니다.

하지만 Claude Code CLI는 기본적으로 Anthropic의 Messages API 규격으로 동작하도록 설계되어 있어, 다른 LLM(예: Google Gemini, OpenAI 등)을 직접 연동하여 사용하기는 어렵습니다.

이번 글에서는 Anthropic API 규격을 구글 Gemini API 규격으로 실시간 변환해 주는 로컬 프록시 서버(LiteLLM)를 구축하여, Claude Code CLI의 연산 백엔드로 Google Gemini 모델을 활용하는 방법과 파이프라인 아키텍처를 상세히 정리합니다.

결론부터 말씀드리면 기술적인 파이프라인 구축은 가능하지만, 에이전트 특성상 발생하는 막대한 토큰 소모 문제로 인해 실무 연동은 비추천합니다.

아래에서 구축 방법과 함께 왜 이런 장애 및 트레이드오프가 발생하는지 상세히 분석해 보겠습니다.

아키텍처 및 연동 원리

Claude Code CLI는 내부적으로 Anthropic 고유의 API 규격(Messages API)을 하드코딩하여 통신합니다.

Google Gemini API 엔드포인트를 직접 지정하면 요청 및 응답 JSON 포맷 차이로 인해 오류가 발생하므로, 중간에 LiteLLM 프록시 서버를 배치합니다.

[Claude Code CLI] 
   │ 
   │  (1) Anthropic JSON Format (Messages API)
   ▼ 
[LiteLLM Proxy (로컬 포트 4000)] 
   │ 
   │  (2) Real-time Payload Translation (Google API Format)
   ▼ 
[Google Gemini API Server]

동작 프로세스

1. Claude Code CLI: 자신이 Anthropic 서버와 통신한다고 인식하며, Anthropic 규격의 JSON 요청을 로컬 프록시(http://127.0.0.1:4000)로 전달합니다.

2. LiteLLM Proxy: 들어온 Anthropic JSON 프로토콜을 Google Gemini API 규격으로 실시간 번환하여 구글 서버로 전달합니다.

3. Google Gemini: 연산을 수행한 후 응답을 반환하면, LiteLLM이 다시 Anthropic 포맷으로 변환하여 Claude Code CLI로 전달합니다.

사전 준비: Gemini API Key 동작 확인

가장 먼저 구글 AI Studio 등에서 발급받은 Gemini API Key가 정상 작동하는지 확인합니다.

터미널에서 curl 명령어를 통해 구글 서버와의 직접 통신 테스트를 진행합니다.

export GEMINI_API_KEY="your_actual_gemini_api_key"

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"contents": [{"parts":[{"text": "hi"}]}]}'

정상적인 JSON 응답(candidates, content 구조)이 수신되면 API Key가 정상 준비된 것입니다.

LiteLLM 프록시 서버 설치 및 설정

LiteLLM은 다양한 AI 제공자(Anthropic, OpenAI, Google 등)의 API 규격을 중앙에서 통합 관리 및 변환해 주는 대표적인 멀티 모델 라우터(Multi-Model Router)입니다.

LiteLLM 설치

독립된 패키지 환경 보장을 위해 pipx를 이용하여 litellm[proxy]를 설치합니다.

# pipx 설치 (macOS Homebrew 기준)
brew install pipx
pipx ensurepath
source ~/.zshrc

# LiteLLM 프록시 패키지 설치
pipx install 'litellm[proxy]'

설정 파일 작성

Claude Code CLI가 보낸 모델 요청을 실제 Gemini 모델로 매핑해 주는 config.yaml 파일을 작성합니다.

model_list:
  - model_name: claude-sonnet-5-20241022    # Claude Code CLI가 요청할 모델명
    litellm_params:
      model: gemini/gemini-2.5-flash        # 연산을 실제로 수행할 Google Gemini 모델
      api_key: "os.environ/GEMINI_API_KEY"  # 시스템 환경변수에서 키 참조
      drop_params: true                     # Gemini에서 지원하지 않는 파라미터 자동 제거

설정 옵션 참고

• drop_params: true: Anthropic API 전용 파라미터(예: thinking, prompt_caching 등)가 Gemini 통신 시 에러를 일으키지 않도록 자동으로 무시/제거하는 중요한 설정입니다.

프록시 서버 구동

작성한 설정 파일을 기반으로 LiteLLM 프록시 서버를 실행합니다.

litellm --config config.yaml --port 4000

정상 구동되면 http://127.0.0.1:4000 주소로 로컬 API 엔드포인트가 활성화됩니다.

Claude Code CLI 연동 및 테스트

이제 새로운 터미널 창을 열고, Claude Code CLI가 공식 Anthropic API 대신 로컬 프록시(http://127.0.0.1:4000)를 바라보도록 환경 변수를 지정하여 실행합니다.

ANTHROPIC_BASE_URL="http://127.0.0.1:4000" \
ANTHROPIC_API_KEY="sk-ant-api03-dummy1234567890" \
ANTHROPIC_MODEL="claude-sonnet-5-20241022" \
claude -p "테스트 시작: 당신은 누구인가요?"

실제 응답 확인

⚠ claude.ai connectors are disabled because ANTHROPIC_API_KEY or another auth source is set...

저는 Google에서 개발한 대규모 언어 모델인 Gemini입니다.

인터페이스는 그대로 유지하면서 내부 엔진만 Google Gemini로 전환된 것을 확인할 수 있습니다.

실무 활용 시 주의사항 및 한계점

이 프록시 구조를 통해 기술적인 연동은 완료되었으나, 실제 프로젝트 적용 시 다음과 같은 치명적인 한계점이 발생합니다.

과도한 토큰 소모

가장 큰 문제는 토큰 소모량이 비정상적으로 높다는 점입니다.

단순히 블로그 내용에 대한 텍스트 검수 및 수정 작업을 1~2회 요청했을 뿐인데도, Gemini API 사용량 한도의 30~40%가 순식간에 소모되는 현상이 발생했습니다.

원인은 Claude Code CLI가 단순한 챗봇이 아닌 '자율 에이전트(Agent)'로 동작하기 때문입니다.

CLI는 사용자의 짧은 질문 하나를 처리할 때도 다음과 같은 방대한 데이터를 매 요청마다 통째로 전송합니다.

• Claude Code의 복잡한 내부 시스템 프롬프트

• 에이전트가 사용할 수 있는 모든 도구(Tool)의 JSON 스키마 정의

• 현재 파일 시스템 상태 및 이전 대화의 누적 맥락

결과적으로 백그라운드에서는 수만 토큰의 컨텍스트가 매번 API로 전송되며, 이는 곧 API Rate Limit(속도 제한) 오류나 일일 쿼터 고갈이라는 장애를 유발합니다.

Tool Calling 호환성 이슈

Claude Code CLI는 파일 읽기(Read), 수정(Edit), 쉘 명령어 실행(Bash) 등 복잡한 에이전트 도구를 적극적으로 사용합니다.

LiteLLM이 Anthropic의 <tools> 스키마를 Gemini의 규격으로 변환하지만, 단순 요약 작업은 원활하나, 복잡한 정규식 기반 코드 수정이나 서브에이전트 연쇄 호출 시 스키마 불일치로 프로세스가 중단될 위험이 있습니다.

Claude 공식 API와의 병행 필요성

drop_params: true 설정으로 인해 Claude 특유의 Extended Thinking(사고 과정 출력)이나 Prompt Caching 등의 최적화 기능은 작동하지 않습니다.

따라서 안정적인 실무 환경을 원한다면, Claude 공식 API 키를 활용하는 것이 훨씬 효율적입니다.

결론

LiteLLM 프록시 서버를 이용해 Anthropic Messages API를 Gemini API로 변환하는 파이프라인은 기술적으로 흥미로운 시도입니다.

설정 파일 몇 줄만으로 거대한 에이전트의 두뇌(LLM)를 교체해 볼 수 있다는 점은 매력적입니다.

하지만 에이전트 특유의 방대한 컨텍스트 전송 구조로 인해 토큰 소모가 극심하여, 실무 개발이나 일상적인 코딩 보조 용도로는 비추천합니다.

가벼운 텍스트 리뷰만으로도 할당량의 30~40%가 증발하는 것은 효율성 측면에서 수용하기 어려운 트레이드오프입니다.

안정적인 에이전트 활용을 위해서는 가급적 원래 설계에 맞는 Claude 공식 API를 사용하실 것을 권장합니다.