CLIProxyAPI 딥다이브
— AI 구독 계정을 OpenAI/Gemini/Claude 호환 API로 바꾸는 Go 게이트웨이

1프로젝트 한 줄 요약

CLIProxyAPI는 "Claude Pro/Max·ChatGPT Plus·Gemini 같은 월정액 AI 구독 계정을, 표준 API처럼 프로그램에서 호출할 수 있게 중계해주는 프록시 서버"다. 이름을 풀면 CLI(각 벤더의 공식 명령줄 도구가 로그인한 세션) + Proxy(그 세션을 대신 붙잡고 요청을 중계) + API(OpenAI/Claude/Gemini 호환 HTTP 엔드포인트로 노출). 즉 "내가 이미 구독한 계정을, API 키를 따로 발급받지 않고도 API 클라이언트·SDK·에이전트에서 쓰게 해준다".

2왜 지금 주목받는가

2026년 개발자들에게 AI 도구 비용은 현실적 고민이다. 에이전트·자동화를 굴리면 종량제 API 토큰 요금이 순식간에 불어난다. 반면 Claude Max·ChatGPT Pro 같은 월정액 구독은 한도가 넉넉하지만 "공식 앱 안에서만" 쓸 수 있다. CLIProxyAPI는 이 간극을 정확히 노린다 — 이미 낸 구독료로 API를 쓰게 해주는 것. 여기에 여러 벤더·여러 계정을 한 엔드포인트로 묶는 실용성이 더해져 X·해커뉴스에서 화제가 되며 Daily 최상위로 올라왔다. (TrendShift의 굵은 숫자는 별 수가 아니라 사회적 언급 모멘텀이다.)

주목 포인트 1 — "구독을 API로" (토큰 과금 회피)

핵심 가치 제안은 명확하다: 종량제 API 대신, 이미 결제한 정액 구독을 API처럼 쓴다. Cursor·Windsurf가 토큰 단위로 과금하는 것과 달리, 구독 한도 안에서 자율 에이전트·배치 작업을 돌릴 수 있다. DesktopCommanderMCP 같은 도구가 내세운 "API 토큰이 아닌 구독으로 굴린다"와 같은 철학이되, CLIProxyAPI는 이를 표준 API 엔드포인트 형태로 일반화했다.

주목 포인트 2 — 멀티 프로바이더를 하나의 엔드포인트로

Codex(ChatGPT)·Claude Code·Gemini CLI·Google Antigravity·Moonshot Kimi·xAI Grok·Vertex AI·AI Studio까지 10종의 상류 실행기(executor)를 내장하고, 이를 전부 OpenAI/Claude/Gemini 호환 포맷으로 노출한다. 클라이언트는 어느 모델을 쓰든 익숙한 OpenAI API 한 벌로 말을 걸면 된다 — 백엔드가 무엇이든 프록시가 형식을 번역해준다.

주목 포인트 3 — 계정 풀 로드밸런싱 · 자동 장애조치

여러 계정을 등록하면 round-robin(순번 분배)이나 fill-first(한 계정을 다 쓰고 다음으로) 전략으로 요청을 여러 구독에 분산한다. 한 계정이 한도 초과(429)되면 자동으로 다른 계정으로 넘기고(cooldown/failover), 세션 고정(session affinity)으로 대화 연속성도 유지한다. "여러 API 키를 묶어 한도를 늘리는" 게이트웨이의 전형적 기능을 구독 계정에 적용한 셈.

주목 포인트 4 — 매우 활발한 개발 + 임베더블 SDK

최신 커밋이 2026-07-13(PR #4190)일 만큼 개발이 빠르고, 릴리스가 v7.2.71까지 찍혔다. 게다가 sdk/ 아래에 Go 라이브러리로 임베드할 수 있는 미러 구조를 제공해, 다른 프로젝트가 CLIProxyAPI를 통째로 삼켜 쓰기도 한다(README의 "built on" 목록). 파일·Postgres·Git·S3 토큰 저장소, 클러스터(control-plane) 모드까지 갖춘, 완성도 높은 인프라 소프트웨어.

3기술 스택 전체 지도

CLIProxyAPI는 단일 Go 모듈이다. 모듈 경로가 github.com/router-for-me/CLIProxyAPI/v7로, 메이저 버전 7이 경로에 박혀 있다(Go의 semantic import versioning). 언어는 Go 1.26.0(꽤 최신), 빌드에 CGO_ENABLED=1이 필요하다 — C-ABI 동적 라이브러리 플러그인을 지원하기 때문(§4-6). 규모는 937개 추적 파일 중 766개가 .go, 총 약 247,614줄로, 사실상 Go 100%다.

HTTP · JSON · 네트워크 계층

저장소 · 운영 · TUI 계층

배포 · 빌드

Dockerfile은 golang:1.26-bookworm(빌더) → debian:bookworm(런타임) 2단계로, CGO_ENABLED=1과 ldflags로 버전/커밋/빌드일자를 주입하고 EXPOSE 8317을 연다(공식 이미지 eceasy/cli-proxy-api). docker-compose.yml은 API 포트 8317과 함께 OAuth 콜백용 포트들(8085·1455·54545·51121·11451)을 매핑하고, config.yaml·auths/·logs/를 볼륨으로 뺀다. GitHub Actions의 release.yaml은 darwin·windows·linux(glibc/musl)·freebsd 멀티플랫폼 매트릭스 빌드를 돌린다(musl/freebsd는 플러그인 없는 no-plugin 변형).

4아키텍처 심화 분석

이 섹션의 첫 문장만 기억해도 절반은 이해한 것이다: CLIProxyAPI = "들어온 요청을 표준 포맷으로 정규화 → 알맞은 계정을 고르고 → 그 상류의 포맷으로 번역해 보내고 → 응답을 다시 클라이언트 포맷으로 되번역"하는 파이프라인이다. 이 파이프라인이 세 개의 큰 근육 위에서 돈다 — ①번역 계층(translator) · ②상류 실행기(executor) · ③라우팅 지휘자(conductor). 각각이 이 레포에서 가장 큰 패키지들이다.

4-0. 전체 요청 흐름 한눈에

4-1. 번역 계층 — 스키마가 제각각인 API들을 하나로 잇기

internal/translator/는 이 레포에서 가장 큰 패키지다(약 45,554줄). 문제의 본질은 이렇다: OpenAI·Claude·Gemini·Codex는 요청/응답 JSON 스키마가 전부 다르다. 클라이언트가 OpenAI 포맷으로 보냈는데 뒤에 붙은 건 Claude라면, 누군가 형식을 바꿔줘야 한다. CLIProxyAPI는 이를 (출발 포맷, 도착 포맷) 쌍을 키로 하는 변환 레지스트리로 푼다.

// sdk/translator/registry.go — (from,to) 쌍으로 변환 함수를 등록
// 7개 표준 포맷: openai, openai-response, claude, gemini,
//                codex, antigravity, interactions
translator.Register(
    "claude", "openai",          // Claude 요청 → OpenAI 스키마
    ConvertClaudeRequestToOpenAI,   // 요청 변환 함수
    ConvertOpenAIResponseToClaude,  // 응답 되번역 함수
)
// 이런 init.go가 26개 — 각자 한 방향(쌍)을 배선한다

변환 함수는 전부 순수 함수 func(model string, rawJSON []byte, stream bool) []byte 꼴이다 — 앞서 본 gjson/sjson으로 도착 스키마의 JSON 틀을 만들고 필드를 하나씩 옮겨 담는다. 스트리밍 변환은 청크 슬라이스([][]byte)를 돌려준다. 만약 (출발,도착)에 맞는 변환기가 없으면 model 필드만 정규화한 채 그대로 통과(passthrough)시킨다.

4-2. 상류 실행기 — 벤더 10종을 같은 인터페이스로

internal/runtime/executor/(약 39,900줄)에는 상류 제공자마다 하나씩 Executor가 있다. 전부 같은 계약(Identifier() + Execute/ExecuteStream)을 구현해, 지휘자가 어느 상류든 똑같이 다룰 수 있다.

// sdk/cliproxy/executor/types.go — 모든 실행기가 지키는 계약
type Request struct {
    Model    string
    Payload  []byte
    Format   sdktranslator.Format
    Metadata map[string]any
}
type StreamResult struct {
    Headers http.Header
    Chunks  <-chan StreamChunk   // 스트리밍은 채널로 흘려보냄
}
type StatusError interface {   // 401/402/429를 인증상태로 올림
    error
    StatusCode() int
}

4-3. OAuth 인증 — 공식 CLI의 로그인 흐름을 그대로 밟기

구독 계정에 붙으려면 각 벤더의 OAuth2 + PKCE 로그인을 통과해야 한다. CLIProxyAPI는 공식 CLI 도구가 쓰는 것과 동일한 client ID를 그대로 사용한다 — 이게 "API 키 없이" 가능한 이유이자, 동시에 §6에서 짚을 회색지대의 뿌리다.

// internal/auth/claude/anthropic_auth.go (개념 발췌)
AuthURL  = "https://claude.ai/oauth/authorize"
TokenURL = "https://api.anthropic.com/v1/oauth/token"
ClientID = "9d1c250a-...-5944d1962f5e"  // 실제 Claude Code 클라이언트 ID
Redirect = "http://localhost:54545/callback"  // 로컬 콜백 서버
Scopes   = "user:profile user:inference user:sessions:claude_code ..."

-claude-login·-codex-login·-antigravity-login·-kimi-login·-xai-login 같은 명령을 실행하면, 프록시가 로컬 포트에 콜백 서버를 잠깐 띄우고 브라우저 OAuth를 유도해 토큰을 받는다(Codex는 device-code 흐름도 지원). 받은 토큰은 기본적으로 ~/.cli-proxy-api의 JSON 인증 레코드로 저장되며(FileTokenStore), 백그라운드 루프가 만료 전 자동으로 갱신한다(auth-auto-refresh-workers). 저장소는 Postgres·Git·S3로도 바꿀 수 있다.

4-4. 라우팅 지휘자(conductor) — 계정 풀을 지휘하는 뇌

sdk/cliproxy/auth/conductor.go는 6,157줄로 이 레포에서 가장 큰 단일 파일이다. 등록된 여러 계정 중 어느 것으로 이 요청을 보낼지를 결정하고, 실패하면 다른 계정으로 넘기며, 토큰 갱신·쿨다운을 총괄한다.

4-5. API 표면 · SSE 스트리밍

internal/api/server.go(2,018줄, Gin)가 라우트 표다. OpenAI(/v1/chat/completions·/v1/completions·/v1/responses+ws·/v1/images/*·/v1/videos/*), Claude(/v1/messages·count_tokens), Gemini(/v1beta/models 등), 그리고 Codex 원문 통과(/backend-api/codex/responses)를 연다. 스트리밍은 SSE(text/event-stream)로, 변환기가 청크 슬라이스를 흘려보내고, streaming.keepalive-seconds가 빈 줄을 주기적으로 보내 유휴 타임아웃을 방지한다.

운영 측면에서 특이한 규약: 상류 연결이 열린 뒤에는 타임아웃을 걸지 않는다(긴 에이전트 스트림을 지원하려고). 타임아웃은 "계정 획득 단계"에서만 허용된다. log.Fatal은 금지, 토큰은 로그에 절대 남기지 않는다는 규칙도 AGENTS.md에 명문화돼 있다.

4-6. 관리 API · 플러그인 호스트

/v0/management/* 그룹은 설정·API 키·프로바이더별 키 CRUD·라우팅 전략·플러그인 설치·로그·사용량·쿼터 리셋을 웹으로 제어한다. remote-management.secret-key가 비어 있으면 이 그룹 전체가 404로 잠긴다(로컬에서도 키 필요). 번들 웹 관리 패널이 /management.html로 제공된다.

더 나아가 internal/pluginhost/(약 17,800줄)는 C-ABI 동적 라이브러리 플러그인 호스트다 — Go/C/Rust로 짠 플러그인이 실행기·번역기·인증 제공자·스케줄러 등 ~24종의 확장점에 꽂힌다. 다만 플러그인은 "프로세스 안에서 신뢰되는 코드"라 기본 비활성이고, 설치형 플러그인 스토어가 따로 있다(§6 주의).

5디렉토리 구조 해부

구조를 읽는 요령: "internal은 진짜 구현, sdk는 남이 임포트하는 공개 얼굴"이다. 두 트리가 상당 부분 짝을 이룬다 — internal/은 이 서버 자체의 비공개 구현이고, sdk/는 다른 Go 프로젝트가 CLIProxyAPI를 라이브러리로 삼킬 때 쓰는 안정적 표면이다. 처음 읽는다면 별표(★) 여섯 곳부터 — cmd/server/main.go(부팅) → internal/api/server.go(라우트) → internal/translator/(번역) → internal/runtime/executor/(상류) → sdk/cliproxy/auth/conductor.go(지휘) → sdk/translator/registry.go(변환 등록) 순.

6학습 포인트

API 게이트웨이 · 포맷 번역 계층 설계

이 레포의 가장 값진 교재는 "서로 다른 API 스키마를 어떻게 하나로 잇는가"다. (from,to) 레지스트리 + 정규형(canonical) 패턴 + 순수 함수 변환기는 컴파일러의 IR, 데이터 ETL, 마이크로서비스 어댑터 어디서나 재사용되는 보편 설계다. gjson/sjson으로 "구조체 없이 JSON을 수술"하는 실전 코드도 여기서 통째로 읽을 수 있다.

OAuth2 + PKCE 로그인 흐름의 실물

"브라우저를 열어 로그인하고 → 로컬 콜백 서버가 코드를 받고 → 토큰으로 교환하고 → 백그라운드로 자동 갱신"하는 OAuth2+PKCE 전 과정이 벤더별로 구현돼 있다. OAuth를 글로만 배운 사람에게, 콜백 포트·PKCE 챌린지·refresh 루프가 실제 코드로 어떻게 생겼는지 보여주는 살아있는 예제.

계정 풀 로드밸런싱 · 장애조치

conductor.go의 round-robin/fill-first·쿨다운·세션 고정·재시도는 "여러 백엔드를 묶어 한도를 늘리고 장애를 견디는" 분산 시스템의 축소판이다. 로드밸런서·API 게이트웨이·프록시를 설계할 때 필요한 개념(헬스체크·서킷브레이커 유사 쿨다운·스티키 세션)을 한 파일에서 배운다.

Go 서버 엔지니어링 관례

Gin 라우팅·SSE 스트리밍·typed 저장소 추상화(파일/Postgres/Git/S3를 같은 인터페이스로)·fsnotify 핫리로드·Bubbletea TUI·멀티플랫폼 릴리스 매트릭스까지 — 규모 있는 Go 인프라 서비스의 표준 관례가 한 레포에 모여 있다. "log.Fatal 금지, 토큰 로깅 금지, 연결 후 타임아웃 금지" 같은 규약을 AGENTS.md에 문서화한 것도 팀 엔지니어링 참고가 된다.

7하드웨어 · 시스템 요구사항

현실 점검: CLIProxyAPI를 돌리는 데 필요한 건 성능 좋은 서버가 아니라 유효한 구독 계정과, 그 구독을 이렇게 쓰는 것이 약관상 괜찮은지에 대한 스스로의 판단이다. 기술적 진입장벽은 낮지만(가벼운 Go 바이너리), 실질적 진입장벽은 §6의 회색지대에 있다. 학습 목적이라면 구독 없이도 소스만으로 충분히 공부할 수 있다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크