알짜게시판

API 키 없이 Gemini를 로컬 API 서버로 띄우기

Gemini API를 쓰려면 Google AI Studio에서 API 키를 발급받아야 한다. 무료 티어가 있긴 하지만, 분당 요청 수와 모델 접근에 제약이 있고, 특히 gemini-2.5-pro 같은 상위 모델은 금방 쿼터가 소진된다. 개인 Google 계정에 이미 Gemini 구독이 연결되어 있거나, 무료 Google One 플랜을 쓰고 있다면 그 쿼터를 프로그래밍 방식으로 활용하고 싶어지는 건 자연스러운 흐름이다. 문제는 Gemini 웹 인터페이스는 브라우저에서만 동작하고, 이를 API처럼 호출하는 공식적인 방법이 없다는 것이다.

CLIProxyAPI는 이 지점을 파고든 오픈소스 프로젝트다. Gemini CLI의 OAuth 인증 흐름을 그대로 활용해서, 구글 계정으로 로그인한 뒤 로컬에 OpenAI 호환 API 서버를 띄운다. API 키 발급 없이, 브라우저 로그인 한 번으로 http://127.0.0.1:8317/v1/chat/completions 엔드포인트를 사용할 수 있게 된다. OpenAI SDK를 그대로 base_url만 바꿔서 쓸 수 있기 때문에, 기존 코드 수정이 거의 없다.

CLIProxyAPI 다운로드 및 config.yaml 구성

GitHub 릴리즈 페이지(https://github.com/router-for-me/CLIProxyAPI/releases)에서 Windows 바이너리를 받는다. 실행 파일 하나(cli-proxy-api.exe)가 전부다. 별도 설치 과정이 없고, 원하는 폴더에 풀어두면 된다. 이 글에서는 D:\CLIProxyAPI\에 압축을 해제한 기준으로 진행한다.

실행 전에 config.yaml을 작성해야 한다. 같은 폴더에 아래 내용으로 파일을 만든다.

host: "127.0.0.1"
port: 8317
auth-dir: "D:/CLIProxyAPI/auth"
api-keys:
  - "local"

host를 127.0.0.1로 고정하면 로컬 머신에서만 접근 가능하다. 외부에서도 접근하려면 ""로 바우면 모든 인터페이스에 바인딩된다. auth-dir은 OAuth 토큰 파일이 저장될 경로인데, 슬래시 방향에 주의한다. Windows 경로지만 YAML에서는 /를 써야 파싱 오류가 없다. api-keys는 이 서버에 요청할 때 Authorization 헤더에 넣을 값이다. local로 설정했으니 Bearer local을 쓰면 된다. 별도의 providers 블록은 필요 없다. OAuth 로그인 후 auth-dir에 저장된 파일을 서버가 자동으로 감지한다.

Google 계정 OAuth 로그인 — 웹 로그인으로 인증 토큰 발급

서버를 먼저 실행하기 전에 로그인 절차를 진행해야 한다. 터미널에서 아래 명령을 실행한다.

D:\CLIProxyAPI\cli-proxy-api.exe --login

실행하면 브라우저가 자동으로 열리면서 Google 계정 로그인 화면이 나타난다. 로그인 후 권한 승인을 하면 터미널로 돌아와서 다음 선택지가 표시된다.

Select login mode:
  1. Code Assist  (GCP project, manual selection)
  2. Google One   (personal account, auto-discover project)
Enter choice [1/2] (default: 1):

개인 Google 계정을 쓴다면 2를 입력한다. 그러면 GCP(Google Cloud Platform) 프로젝트를 자동으로 탐색하고, high-kite-bv9qn 같은 형태의 프로젝트 ID를 자동 할당한다. 이 과정이 끝나면 auth-dir에 gemini-계정명-프로젝트ID.json 형태의 파일이 생성된다. 이 파일이 OAuth 토큰이다. 만료 시 자동으로 갱신되며, 서버가 15분 간격으로 상태를 점검한다. Code Assist 모드(1번)는 Google Workspace나 기업 GCP 프로젝트를 직접 지정할 때 쓴다. 개인 계정이라면 2번 외에 선택지가 없다고 봐도 된다.

브라우저가 자동으로 열리지 않는 환경, 예를 들어 SSH로 접속한 서버에서 실행하는 경우라면 --no-browser 플래그를 추가한다. 터미널에 인증 URL이 출력되고, 이 URL을 로컬 브라우저에 직접 붙여넣어 로그인하면 된다.

D:\CLIProxyAPI\cli-proxy-api.exe --login --no-browser

서버 실행 및 모델 확인

로그인이 완료됐으면 서버를 실행한다.

D:\CLIProxyAPI\cli-proxy-api.exe

정상적으로 인증 파일이 감지되면 로그에 아래처럼 출력된다.

server clients and configuration updated: 1 clients (1 auth entries + ...)

0 clients로 남아 있다면 auth-dir 경로가 잘못됐거나 로그인 파일이 없는 상태다. 경로를 다시 확인한다. 서버가 뜬 뒤 사용 가능한 모델 목록은 아래 명령으로 확인한다.

curl http://127.0.0.1:8317/v1/models -H "Authorization: Bearer local"

현재 기준으로 응답에 포함되는 모델은 다음과 같다.

gemini-2.5-flash
gemini-2.5-flash-lite
gemini-2.5-pro
gemini-3-flash-preview
gemini-3-pro-preview
gemini-3.1-pro-preview
gemini-3.1-flash-lite-preview

gemini-2.5-pro는 개인 계정의 무료 쿼터가 하루 단위로 초기화된다. 쿼터가 소진된 경우 429 오류(RESOURCE_EXHAUSTED)가 반환된다. 이 경우 gemini-3-flash-preview로 대체하거나 다음 날 다시 시도하면 된다.

실제 요청 테스트 — gemini-3-flash-preview 응답 확인

gemini-3-flash-preview 모델로 실제 요청을 보내면 아래처럼 응답이 온다.

curl http://127.0.0.1:8317/v1/chat/completions ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer local" ^
  -d "{\"model\": \"gemini-3-flash-preview\", \"messages\": [{\"role\": \"user\", \"content\": \"안녕!\"}]}"

응답 예시는 다음과 같다.

{
  "id": "fgfRadnJDaL6694P6aWLsAM",
  "object": "chat.completion",
  "model": "gemini-3-flash-preview",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "안녕하세요! 반가워요. 오늘 어떤 도움을 드릴까요?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 3,
    "completion_tokens": 22,
    "total_tokens": 231
  }
}

응답 구조가 OpenAI의 chat.completions 응답 형식과 동일하다. usage.completion_tokens_details.reasoning_tokens가 206으로 잡혀 있는데, 이는 모델 내부의 추론(chain-of-thought) 과정에서 소비된 토큰이다. 출력 토큰은 22개지만 내부 처리에는 206 토큰이 쓰인 셈이다. Python에서 OpenAI SDK를 쓰던 코드라면 base_url과 api_key만 바꾸면 그대로 동작한다.

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8317/v1",
    api_key="local"
)

response = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[{"role": "user", "content": "안녕!"}]
)
print(response.choices[0].message.content)

Cursor, Cline, Continue 같은 IDE 확장 툴도 OpenAI 호환 엔드포인트를 지원하므로, Base URL을 http://127.0.0.1:8317/v1로 설정하면 바로 연결된다.

쿼터 한계와 멀티 계정 운용 시 고려할 점

이 방식의 한계는 개인 Google 계정의 무료 쿼터에 종속된다는 점이다. 공식 문서 기준으로 Gemini CLI OAuth를 통한 무료 사용은 분당 60회, 하루 1,000회 요청으로 제한된다. 단일 계정으로 집중적인 요청을 보내면 금방 소진된다. CLIProxyAPI는 멀티 계정 라운드로빈 로드밸런싱을 지원하므로, --login을 여러 번 실행해 서로 다른 Google 계정을 auth-dir에 추가해두면 서버가 요청을 분산한다. 토큰 파일이 2개 이상이면 로그에 2 auth entries로 표시되고 자동으로 순환한다.

주의할 점은 Google이 Gemini CLI OAuth를 서드파티 소프트웨어에서 사용하는 것을 정책 위반으로 간주할 수 있다는 것이다. 계정 제한이나 접근 차단이 발생할 가능성이 있다. 실제로 일부 사용자에게 계정 제한이 걸렸다는 사례가 보고된 바 있다. 프로덕션 환경이나 업무 중요도가 높은 작업에는 공식 API 키 방식을 쓰는 편이 안전하다. 이 설정은 로컬 개발, 프로토타이핑, 개인 프로젝트 수준에서 쓰는 것이 현실적인 범위다. 서버가 127.0.0.1에 바인딩되어 있는 한 외부 노출은 없으므로, 로컬 환경에서의 보안 위험은 낮다.