본문으로 건너뛰기

CLI Proxy

v1
작성 2026-04-13읽는 시간 8분

Claude Code 토큰이 부족할 때, Gemini를 빌려 쓰는 법

CLI Proxy 구조 — Claude와 Gemini를 연결하는 토큰 공유 파이프라인

이건 뭐예요?​

요리사 한 명으로는 부족한 날이 온다​

바이브 코딩을 하다 보면, Claude Code가 정말 든든한 요리사 같아요. "이거 만들어줘"라고 하면 뚝딱 만들어주거든요.

그런데 요리사가 하루에 만들 수 있는 음식 양에는 한계가 있잖아요. 점심 한 끼 만드는 정도는 괜찮은데, 갑자기 "저녁 뷔페 50인분 준비해줘"라고 하면 한 명으로는 버거워지는 거예요.

Claude Code도 마찬가지예요. 코드 몇 줄 고치고, 버그 잡고, 파일 정리하는 정도는 Pro 구독 토큰(AI가 한 번에 처리할 수 있는 작업량의 단위)으로 충분해요.

그런데 글을 한 편 통째로 쓰게 시키거나, 여러 파일을 한꺼번에 리팩토링(코드를 전면적으로 재구조화하는 작업)하는 식의 대량 작업을 시키면요. 토큰이 순식간에 바닥나요.

그래서 CLI Proxy가 뭔데요?​

CLI Proxy(CLIProxyAPI) 는 이 문제를 해결하는 도구예요. 쉽게 말하면, 다른 AI 구독을 빌려 쓸 수 있게 해주는 중간 통역사예요.

비유하자면 이래요. 여러분 집에 한국어만 하는 요리사(Claude Code)가 있어요. 이 요리사가 바빠서 손이 부족해요. 그래서 옆집에 영어만 하는 요리사(Gemini)를 빌려오고 싶은 거예요. 그런데 우리 집 주방 시스템은 한국어 주문서만 받거든요. CLI Proxy는 영어 요리사한테 한국어 주문서를 영어로 번역해서 전달해주는 통역사 역할을 해요.

기술적으로 풀어볼게요. 구글 Gemini가 응답하는 방식과, Claude Code가 알아듣는 방식은 서로 달라요. 마치 한국어와 영어처럼요. OpenAI 호환 API 형식이라는 건, 대부분의 AI 도구가 "이 형식으로 대화하자"고 약속한 공통 언어 같은 거예요. CLI Proxy는 Gemini의 응답을 이 공통 언어로 바꿔주는 로컬 프록시 서버(내 컴퓨터에서만 동작하는 중간 중계 프로그램)예요. 내 컴퓨터 안에서만 돌아가니까 외부로 데이터가 새어나갈 걱정도 없어요.

CLIProxyAPI는 GitHub에서 25,000개 이상의 별을 받은 오픈소스 프로젝트예요.

우리는 이렇게 쓰고 있어요​

AI//STUDY 글쓰기 파이프라인의 비밀 병기​

지금 여러분이 읽고 있는 이 AI//STUDY 사이트에서, 저희는 CLI Proxy를 글 작성 파이프라인(글을 자동으로 만들어내는 작업 흐름)에 실전으로 쓰고 있어요.

어떤 구조인지 간단히 보여드릴게요. 식당 비유로 하면 더 쉬워요.

  1. Claude Code write-agent(글 쓰는 전문 AI 에이전트)가 메뉴판(글의 주제와 구조)을 짜요
  2. 글 전체를 Claude로 쓰면 토큰이 너무 많이 들어요. 그래서 Gemini에게 초안 작성을 맡겨요 — 옆집 요리사한테 재료 손질을 부탁하는 거예요
  3. 이때 CLI Proxy가 중간에서 Gemini의 응답을 Claude가 알아듣는 형식으로 변환해줘요
  4. Python 스크립트(tools/gemini-draft.py)가 프록시를 통해 Gemini를 호출하고, 결과를 docs/.drafts/ 폴더에 초안으로 저장해요
  5. 마지막으로 Claude editor-agent가 초안을 퇴고(다듬기)해서 완성본을 만들어요

이 방식의 장점이 뭐냐면요.

  • 초안 생성(토큰 많이 드는 작업)은 Gemini가 담당 → Claude 토큰 절약
  • 퇴고(품질 잡는 작업)는 Claude가 담당 → 최종 품질 유지
  • 두 AI의 장점만 조합하는 셈이에요

한번 써볼까요?​

솔직하게 말씀드릴게요. 저도 처음 설정할 때 꽤 헤맸어요. "인증은 어디서 하지?", "왜 모델 목록이 안 뜨지?" 하면서요. 그래서 제가 실제로 삽질한 경험을 바탕으로, 진짜 되는 순서만 정리했어요. 차근차근 한 단계씩 따라오시면 됩니다.

1단계: CLIProxyAPI 다운로드하기​

먼저 프록시 서버 프로그램을 받아야 해요. 마트에서 재료 사오는 것처럼, 첫 번째 할 일은 프로그램을 내려받는 거예요.

CLIProxyAPI GitHub Releases 페이지로 가세요. 페이지에서 가장 위에 있는 게 최신 버전이에요. Assets 목록을 펼치면 다운로드 파일들이 보여요. 본인 컴퓨터에 맞는 걸 받으세요.

운영체제다운로드 파일
WindowsCLIProxyAPI_x.x.x_windows_amd64.zip
Mac (Apple Silicon, M1~M4)CLIProxyAPI_x.x.x_darwin_arm64.tar.gz
Mac (Intel)CLIProxyAPI_x.x.x_darwin_amd64.tar.gz
LinuxCLIProxyAPI_x.x.x_linux_amd64.tar.gz

x.x.x 는 버전 번호예요. 항상 가장 위에 있는 최신 버전을 받으세요.

Mac 사용자라면 Homebrew(맥용 패키지 관리 도구)로 더 간단하게 설치할 수도 있어요.

# Mac 전용 — Homebrew로 한 줄 설치 (Mac이 아니면 건너뛰세요)
brew install cliproxyapi

Windows 사용자는 다운로드한 zip 파일의 압축을 풀면 이런 파일들이 나와요.

  • cli-proxy-api.exe — 이게 프록시 서버 프로그램이에요. 이것만 있으면 돼요.
  • config.example.yaml — 설정 파일 예시. 참고용이에요.
  • README.md, LICENSE — 설명서와 라이선스. 안 봐도 돼요.

cli-proxy-api.exe를 원하는 폴더에 넣어두세요. 저희는 프로젝트 안에 tools/cliproxy/ 폴더를 만들어서 거기에 넣었어요.

여기까지 했으면, 프로그램 준비는 끝이에요. 다음 단계로 넘어가세요.

2단계: 설정 파일 만들기​

프록시 서버한테 "너는 이렇게 동작해"라고 알려주는 설정 파일을 만들 차례예요. 요리사에게 레시피를 건네주는 것과 같아요.

cli-proxy-api.exe가 있는 폴더에 config.yaml 파일을 새로 만들어주세요. 메모장으로 만들어도 돼요. 아래 내용을 그대로 복사해서 붙여넣으세요.

# config.yaml — 최소 설정 (이대로 복사하면 돼요)
host: "127.0.0.1"
port: 8317

api-keys:
  - "my-local-key"

auth-dir: "~/.cli-proxy-api"
debug: false
request-retry: 3

각 줄이 뭘 하는 건지 궁금하시다면 이래요.

설정쉬운 설명
host: "127.0.0.1"내 컴퓨터에서만 접근 가능하게 해요 (외부 차단)
port: 8317프록시가 사용할 문 번호예요 (건물의 호수 같은 거예요)
api-keys프록시에 접속할 때 쓰는 비밀번호 같은 거예요
auth-dir구글 로그인 정보가 저장될 폴더예요
request-retry: 3오류 나면 포기하지 않고 최대 3번 재시도해요

파일을 저장했으면, 설정 완료예요. 다음은 구글 계정 로그인이에요.

3단계: 구글 계정 로그인하기​

여기가 가장 중요한 단계예요. 프록시가 여러분 대신 Gemini한테 말을 걸려면, "나 이 사람이야"라고 구글에게 증명해야 하거든요. CLIProxyAPI 자체에 구글 로그인 기능이 내장되어 있어요.

터미널(명령어를 입력하는 창 — Windows라면 PowerShell, Mac이라면 Terminal)을 열고 아래를 실행하세요.

Windows (PowerShell):

# cli-proxy-api.exe가 있는 폴더로 이동한 뒤, 로그인 모드로 실행
cd C:\원하는경로\cliproxy; .\cli-proxy-api.exe --login

Mac / Linux:

# cli-proxy-api가 있는 폴더로 이동한 뒤, 로그인 모드로 실행
cd ~/원하는경로/cliproxy && ./cli-proxy-api --login

Windows 주의: PowerShell에서는 &&(그리고 실행)가 안 먹혀요. 대신 ;(세미콜론)을 쓰세요. 저도 이거 때문에 에러 나서 한참 헤맸어요.

실행하면 아래처럼 로그인 방식을 선택하는 화면이 나와요.

로그인 모드 선택 화면

2번 Google One을 선택하세요. 개인 구글 계정으로 로그인하는 거예요. 2를 입력하고 Enter를 누르면 브라우저가 자동으로 열려요.

브라우저에서 구글 계정으로 로그인하면 끝이에요. 터미널에 "successful" 메시지가 뜨면 성공이에요.

로그인 성공 후 브라우저는 꺼도 돼요. 인증 토큰(로그인 상태를 기억하는 열쇠 같은 정보)이 내 컴퓨터에 파일로 저장되기 때문에, 한 번 로그인하면 다음부터는 안 물어봐요.

축하해요, 가장 어려운 고비를 넘겼어요. 이제 서버를 켜면 돼요.

4단계: 프록시 서버 실행하기​

로그인이 끝났으면, 이제 프록시 서버를 켜면 돼요. 가게 문을 여는 거라고 생각하세요. 같은 터미널에서 아래를 실행하세요.

Windows (PowerShell):

# 프록시 서버 켜기 (가게 문 열기!)
.\cli-proxy-api.exe

Mac / Linux:

# 프록시 서버 켜기 (가게 문 열기!)
./cli-proxy-api

터미널에 API server started successfully on: 127.0.0.1:8317 이라는 메시지가 나오면 프록시가 정상적으로 켜진 거예요.

이 터미널 창은 끄면 안 돼요! 프록시 서버가 이 창에서 돌아가고 있으니까, 창을 닫으면 프록시도 꺼져요. 최소화해두고 놔두세요.

거의 다 왔어요! 마지막으로 잘 되는지 확인만 하면 끝이에요.

5단계: 잘 되는지 확인하기​

새 터미널 창을 하나 더 열고, 아래를 실행해 보세요. 4단계의 터미널은 그대로 놔두고, 새 창을 여는 거예요.

# 프록시 서버가 살아있는지 확인 (모델 목록이 나오면 성공!)
curl -s http://localhost:8317/v1/models -H "Authorization: Bearer my-local-key"

gemini-2.5-pro, gemini-3-pro-preview 같은 모델 이름들이 JSON(데이터를 정리해서 보여주는 형식) 형태로 쭉 나오면 축하해요, 설정 완료예요!

만약 {"data":[],"object":"list"} 처럼 빈 목록이 나온다면, 3단계 로그인을 다시 해보세요. 프록시 서버를 먼저 끄고(Ctrl+C를 누르면 서버가 꺼져요), --login부터 다시 시작하면 돼요.

저도 처음에 이렇게 헤맸어요​

설정이 한 번에 안 될 수도 있어요. 괜찮아요, 다 그래요. 저도 처음에 이런 삽질을 했거든요. 여러분이 같은 실수를 안 하시도록 미리 정리해뒀어요.

삽질 1: "Gemini CLI를 먼저 설치해야 하는 줄 알았어요"​

처음에는 구글의 Gemini CLI(npm install -g @google/gemini-cli)를 먼저 설치하고, 거기서 구글 로그인을 한 다음에 프록시를 연결해야 하는 줄 알았어요.

Gemini CLI 인증 화면

Gemini CLI 인증은 성공했는데, 정작 프록시 서버를 켜보니 모델이 0개. CLIProxyAPI는 Gemini CLI 인증을 안 써요. 자체 --login 명령어로 별도 인증을 해야 해요. Gemini CLI 설치는 프록시 사용에 필요 없어요.

삽질 2: "Claude Code 안에서 로그인하려고 했어요"​

Claude Code 대화창에서 ! gemini --login 같은 걸 실행하려고 했는데, Claude Code의 ! 명령어는 대화형 입력(Y/N 선택, 브라우저 로그인 등)을 지원하지 않아요. 화면에 "Y를 입력하세요"라고 뜨는데 Y를 칠 수가 없었어요. 자판기에 동전은 넣었는데 버튼이 없는 느낌이었어요.

해결: 로그인은 반드시 Claude Code가 아닌 일반 터미널(PowerShell, Terminal)에서 하세요.

삽질 3: "PowerShell에서 && 가 안 먹혀요"​

Mac/Linux에서 쓰던 습관대로 cd 폴더 && ./실행파일 을 PowerShell에서 쳤더니 에러가 났어요.

해결: Windows PowerShell에서는 && 대신 ;(세미콜론)을 쓰세요. cd 폴더; .\실행파일 이렇게요.

클로드 코드 터미널에서는 이렇게​

프록시 서버가 켜져 있는 상태에서, Claude Code 대화창에서 Gemini를 활용하는 방법이에요. 5단계까지 끝낸 분만 이 섹션을 따라하세요.

프록시 상태 확인​

클로드 코드 대화창에서 !를 맨 앞에 붙이면 터미널 명령어를 바로 실행할 수 있어요.

# 프록시 서버가 살아있는지 확인 (모델 이름이 나오면 OK)
! curl -s http://localhost:8317/v1/models -H "Authorization: Bearer my-local-key"

모델 목록이 나오면, Gemini를 쓸 준비가 된 거예요. 안 나온다면 4단계에서 프록시 서버를 켰는지 확인해 보세요.

.env 파일 만들기​

프로젝트에서 프록시를 쓰려면 .env 파일(프로그램이 참고하는 환경 설정 메모)이 필요해요. 프로젝트 루트 폴더(최상위 폴더)에 만들어주세요.

# .env 파일 생성 — 프록시 연결 정보를 적어두는 메모장 같은 거예요
! cat > .env << 'EOF'
CLIPROXY_URL=http://localhost:8317
CLIPROXY_API_KEY=my-local-key
GEMINI_MODEL=gemini-2.5-pro
EOF

.env 파일은 .gitignore에 이미 등록되어 있어서 Git에 올라가지 않아요. API 키가 외부에 노출될 걱정은 없답니다.

여기까지 설정하면 준비 완료예요. 이제 실제로 Gemini에게 일을 시켜볼까요?

Gemini에게 글 초안 맡기기​

클로드 코드 대화창에 아래처럼 말로 시키면 돼요. ! 없이, 평소에 Claude한테 말하듯이요.

gemini로 해. "Playwright MCP" 주제로 docs/repos/mcp/ 카테고리에 글 초안 작성해줘.

그러면 Claude가 알아서 프롬프트를 조립하고, 프록시를 통해 Gemini를 호출하고, 결과를 docs/.drafts/ 폴더에 저장해줘요.

확인 포인트: docs/.drafts/ 폴더에 .md 파일이 새로 생기면 성공이에요.

꼭 알아두세요 — 사용량과 계정 리스크​

Gemini 무료 티어의 한계​

구글 계정 로그인만으로 하루 1,000건까지 무료로 쓸 수 있어요. 짧은 글 몇 편 정도는 무료로도 충분해요.

하지만 글 생성 파이프라인처럼 긴 프롬프트(AI에게 보내는 긴 요청문)를 자주 보내면 금방 한도에 도달해요. 그래서 구글의 유료 구독인 Google AI Pro(하루 1,500건) 또는 Google AI Ultra(하루 2,000건)를 쓰면 더 넉넉해져요.

티어하루 요청 수비고
무료 (구글 로그인)1,000건기본 제공
Google AI Pro1,500건월 구독
Google AI Ultra2,000건월 구독

과도한 사용은 계정 정지 위험이 있어요​

계정 정지 리스크 — 반드시 읽어주세요

CLI Proxy를 통해 Gemini를 호출하는 것은 구글이 공식으로 의도한 사용 방식이 아닐 수 있어요. 프록시를 통해 대량으로 요청을 보내면 구글 입장에서는 비정상적인 트래픽으로 감지할 수 있어요. 주 구글 계정(Gmail, 드라이브, 유튜브 등이 연결된 계정)으로 사용하는 것은 강력히 비추천해요.

솔직하게 말씀드릴게요. 실제로 커뮤니티에서 보고된 사례들이 있어요.

  • 짧은 시간에 너무 많은 요청을 보내면 **Rate Limit(속도 제한, 일정 시간 안에 보낼 수 있는 요청 수의 한계)**에 걸려서 일시적으로 차단당할 수 있어요
  • 최악의 경우 구글 계정 자체가 정지될 수 있다는 우려도 있어요
  • 특히 여러 계정을 돌려가며 쓰는 행위는 서비스 약관 위반으로 간주될 수 있어요

그래서 이렇게 쓰시길 권해드려요.

  • 하루 요청 수를 본인 티어 한도 안에서 사용하세요
  • 짧은 시간에 수십 건을 연속으로 보내지 마세요
  • 주 계정 대신 별도 구글 계정을 만들어서 사용하세요. 이건 선택이 아니라 사실상 필수예요
  • 계정이 정지되어도 감수할 수 있는 범위에서만 사용하세요

이건 저도 같은 고민을 하면서 쓰고 있어요. 편리한 도구이지만 리스크도 분명 있어요. 용도에 맞게, 절제해서 쓰는 게 중요해요.

이런 분께 추천해요​

CLI Proxy는 Claude Code 토큰이 만성적으로 부족한 바이브 코더에게 꼭 맞는 도구예요. 특히 이런 분께 추천드려요.

  1. 글 작성 파이프라인을 구축하고 싶은 지식 아카이브 운영자 — 문서 사이트를 운영하면서 AI로 글을 자동 생성하고 싶은데, Claude 토큰만으로는 감당이 안 되는 분. Gemini에게 초안을 맡기고 Claude로 퇴고하는 2단계 파이프라인을 쓰면 토큰 비용을 크게 줄일 수 있어요.

  2. 여러 AI를 조합해서 쓰고 싶은 바이브 코더 — "이 작업은 Gemini가 더 잘하고, 저 작업은 Claude가 더 잘해"라는 걸 체감하신 분. CLI Proxy가 있으면 하나의 인터페이스(화면)로 여러 AI를 스위칭(전환)하면서 쓸 수 있어요.

  3. Claude Code Max까지는 부담스럽지만 Pro로는 부족한 분 — 월 구독료를 더 올리지 않고도, 이미 갖고 있는 Gemini 구독을 활용해서 작업량을 늘릴 수 있어요.

참고 링크​

▸개정 이력1건
  • v12026-04-13초판

이 글이 도움이 되었나요?