CLIProxyAPI: CLI 도구의 OAuth 계정으로 OpenAI/Gemini/Claude API 프록시 구축

CLIProxyAPI

API 키 없이 Claude Code, Gemini CLI, OpenAI Codex의 OAuth 구독으로 OpenAI/Gemini/Claude 호환 API를 사용할 수 있다면 어떨까요?

CLIProxyAPI는 이것을 가능하게 합니다. CLI 도구의 OAuth 인증을 프록시 서버로 노출해서, API 키 기반 클라이언트와 SDK가 로컬 또는 멀티 계정 CLI 액세스를 사용할 수 있게 해줍니다.

1) 핵심 개념: CLI OAuth → API 프록시

문제

Claude Code, Gemini CLI, Codex는 OAuth 로그인 기반
대부분의 AI 도구는 API 키 기반 (OpenAI 호환)
둘 사이의 연결이 없음

해결책

┌─────────────────┐      OpenAI API      ┌──────────────────┐
│  AI Coding Tool │ ──────────────────► │  CLIProxyAPI     │
│  (Cursor, Cline)│    (API Key)         │  (localhost:8317)│
└─────────────────┘                      └────────┬─────────┘
                                                  │
                    ┌─────────────────────────────┼─────────────────────────────┐
                    │                             │                             │
                    ▼                             ▼                             ▼
            ┌───────────────┐           ┌───────────────┐           ┌───────────────┐
            │ Claude Code   │           │  Gemini CLI   │           │  OpenAI Codex │
            │  (OAuth)      │           │  (OAuth)      │           │  (OAuth)      │
            └───────────────┘           └───────────────┘           └───────────────┘

CLIProxyAPI가 CLI 도구의 OAuth 세션을 API 키로 변환합니다.

2) 주요 기능

2.1 멀티 프로바이더 지원

프로바이더	인증 방식	기능
Claude Code	OAuth	멀티 계정 로드 밸런싱
Gemini CLI	OAuth	AI Studio, Generative Language Key
OpenAI Codex	OAuth	GPT 모델 지원
Qwen Code	OAuth	멀티 계정
iFlow	OAuth	멀티 계정
Amp CLI	Provider routing	IDE 확장 지원

2.2 API 호환성

OpenAI 호환: /v1/chat/completions, /v1/models
Gemini 호환: /v1beta/models/:model:generateContent
Claude 호환: /v1/messages
Responses API: OpenAI Responses 지원

2.3 로드 밸런싱

# config.yaml
routing:
  strategy: "round-robin"  # 또는 fill-first

quota-exceeded:
  switch-project: true        # 할당량 초과 시 프로젝트 전환
  switch-preview-model: true  # 프리뷰 모델로 자동 전환

전략:

round-robin: 계정을 순차적으로 순환
fill-first: 하나의 계정이 가득 찰 때까지 사용 후 전환

2.4 재시도 & 폴백

request-retry: 3              # HTTP 실패 시 재시도 횟수
max-retry-credentials: 0      # 0 = 모든 사용 가능한 계정 시도
max-retry-interval: 30        # 쿨다운 최대 대기 시간 (초)

3) 설정 구조

3.1 기본 설정

# 서버 설정
host: ""           # 모든 인터페이스 바인딩
port: 8317         # 기본 포트

# TLS (선택)
tls:
  enable: false
  cert: ""
  key: ""

# API 키
api-keys:
  - "your-api-key-1"
  - "your-api-key-2"

# 프록시 (선택)
proxy-url: ""      # socks5://user:pass@host:port

3.2 관리 API

remote-management:
  allow-remote: false       # 로컬호스트만 접근 허용
  secret-key: ""            # 관리 키 (비워두면 비활성화)
  disable-control-panel: false

3.3 계정 등록

entries:
  - provider: claude-code
    account: account1@example.com
    project: default-project

  - provider: gemini-cli
    account: account2@gmail.com
    project: gemini-project

4) Amp CLI 통합

CLIProxyAPI는 Amp CLI와 Amp IDE 확장을 지원합니다:

# Amp용 provider 라우팅
# /api/provider/{provider}/v1... 패턴

기능:

Provider 라우트 별칭
OAuth 인증 관리
스마트 모델 폴백
모델 매핑: 예: claude-opus-4.5 → claude-sonnet-4

5) SDK 사용

CLIProxyAPI는 재사용 가능한 Go SDK를 제공합니다:

import "github.com/router-for-me/CLIProxyAPI/sdk"

// 프록시 임베딩
proxy := sdk.NewProxy(config)
proxy.Start()

SDK 문서:

사용법: docs/sdk-usage.md
고급 (executors & translators): docs/sdk-advanced.md
접근 제어: docs/sdk-access.md
감시자: docs/sdk-watcher.md

6) 설치 방법

Docker

docker-compose up -d

# docker-compose.yml
services:
  cliproxyapi:
    image: routerforme/cliproxyapi:latest
    ports:
      - "8317:8317"
    volumes:
      - ./config.yaml:/app/config.yaml
      - ~/.cli-proxy-api:/root/.cli-proxy-api

바이너리

# GitHub Releases에서 다운로드
./cli-proxy-api

소스 빌드

git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
go build -o cli-proxy-api ./cmd/cli-proxy-api

7) 사용 예시

Claude Code 계정 연결

# 1. CLIProxyAPI 실행
./cli-proxy-api

# 2. Claude Code OAuth 인증
# 브라우저가 열리고 로그인

# 3. API 키로 접근
curl http://localhost:8317/v1/chat/completions \
  -H "Authorization: Bearer your-api-key-1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Cursor에서 사용

API Base URL: http://localhost:8317/v1
API Key: your-api-key-1
Model: claude-sonnet-4

8) 생태계 프로젝트

CLIProxyAPI 기반 프로젝트들:

프로젝트	설명
vibeproxy	macOS 메뉴 바 앱
CCS	Claude 계정 빠른 전환 CLI
ProxyPal	macOS GUI 관리 도구
Quotio	실시간 할당량 추적
CodMate	macOS SwiftUI 관리 앱
ProxyPilot	Windows TUI + 시스템 트레이
霖君	크로스 플랫폼 데스크톱 앱
CLIProxyAPI Dashboard	웹 기반 관리 대시보드

9) 대안 프로젝트

CLIProxyAPI에서 영감을 받은 프로젝트들:

프로젝트	설명
9Router	Next.js 구현, 웹 대시보드 포함
OmniRoute	스마트 라우팅, 캐싱, 관측 가능성

마치며: OAuth 구독을 API로 변환

CLIProxyAPI는 CLI 도구의 OAuth 세션을 API 키 기반 서비스로 변환합니다.

“API 키 없이, 내 OAuth 구독으로 모든 AI 도구를 사용한다.”

특히 인상적인 점:

멀티 계정 로드 밸런싱: 계정을 순환하며 할당량 초과 방지
자동 폴백: 실패 시 다른 계정/모델로 전환
다양한 프로바이더: Claude, Gemini, Codex, Qwen, iFlow
풍부한 생태계: GUI 앱, 대시보드, CLI 도구

이 패턴은 OAuth 기반 서비스를 API로 노출하는 일반적인 해결책이 될 수 있습니다. API 키 없이 구독을 최대한 활용하고 싶은 사용자에게 완벽한 솔루션입니다.

🔗 관련 정보

GitHub: https://github.com/router-for-me/CLIProxyAPI
문서: https://help.router-for.me/
관리 API: MANAGEMENT_API.md
Amp CLI 가이드: https://help.router-for.me/agent-client/amp-cli.html