clco-proxy

Anthropic-compatible multi-provider LLM proxy for Claude Code. Use cheaper models from 42+ providers instead of expensive Claude subscriptions.

                          clco-proxy
                        ┌──────────────┐
  Claude Code ──────────►              ├──── Mode A ──── DeepSeek / GLM / Kimi ...
  (thinks it's talking   │   localhost   │                (Anthropic passthrough)
   to Anthropic API)     │   :8080      │
                         │              ├──── Mode B ──── Gemini / GPT / Groq ...
  ANTHROPIC_BASE_URL ───►              │                (OpenAI translation)
                         └──────────────┘

The proxy sits between Claude Code and your chosen LLM provider, translating API calls in real-time. Claude Code thinks it's talking to Anthropic's API, while actually using whichever provider you configured.

한국어 문서 보기

✨ Features

• 42+ LLM Providers — DeepSeek, Gemini, GPT-5.5, Groq, OpenRouter, Ollama, and dozens more
• Two Translation Modes — Native Anthropic passthrough or full OpenAI format conversion
• Subscription Stealth — Use existing ChatGPT Plus, Gemini Ultra, GitHub Copilot subscriptions through Claude Code
• Smart Model Mapping — Claude's opus/sonnet/haiku tiers auto-map to your best available models
• Auto Model Detection — @auto markers detect best models from provider APIs, cached with 24h TTL
• Background Cache Refresh — Server boot auto-refreshes model caches for all configured providers
• Environment Backup/Restore — clco-proxy run backs up existing Claude settings; clco-proxy restore recovers them
• Full Streaming + Tool Use — SSE streaming with ping keepalive, complete function calling lifecycle

🚀 Quick Start

Prerequisites: Bun >= 1.0

# 1. Initialize config (interactive setup)
npx clco-proxy config init

# 2. Start the proxy daemon
clco-proxy start

# 3. Launch Claude Code through the proxy
clco-proxy run

Your config lives at ~/.clco-proxy/config.json. Here's a minimal example using DeepSeek in Anthropic-compatible mode:

{
  "port": 8080,
  "providers": [
    {
      "id": "deepseek",
      "name": "DeepSeek",
      "apiKey": "sk-your-key",
      "baseUrl": "https://api.deepseek.com/anthropic",
      "models": ["deepseek-v4-flash", "deepseek-v4-pro"],
      "anthropicCompat": true
    }
  ],
  "modelMapping": {
    "opus": { "provider": "deepseek", "model": "deepseek-v4-pro" },
    "sonnet": { "provider": "deepseek", "model": "deepseek-v4-flash" },
    "haiku": { "provider": "deepseek", "model": "deepseek-v4-flash" },
    "default": { "provider": "deepseek", "model": "deepseek-v4-flash" }
  }
}

🔌 Supported Providers

Mode A — Native Anthropic Passthrough

Zero translation overhead. These providers speak the Anthropic API natively.

Mode B — OpenAI-Compatible Translation

Full Anthropic-to-OpenAI format conversion, including streaming and tool use.

💳 Subscription Stealth

Use existing paid subscriptions through Claude Code. No per-token charges.

# Login to a subscription provider
clco-proxy subscription login chatgpt    # Auto-detects OAuth from Codex CLI
clco-proxy subscription login gemini     # API key from Google AI Studio → auto-detects tier
clco-proxy subscription login copilot    # Device flow OAuth in browser

Gemini Ultra: Use the free API key from Google AI Studio — if you have a Google AI Ultra subscription ($249.99/mo), the API key linked to your account automatically unlocks more models (e.g. gemini-3.1-pro-preview). clco-proxy detects your tier and picks the best available models automatically.

📖 CLI Reference

# Setup
clco-proxy config init                       # Interactive config wizard
clco-proxy config show                       # Print current config

# Daemon management
clco-proxy start                             # Start proxy daemon
clco-proxy stop                              # Stop daemon
clco-proxy status                            # Check daemon status
clco-proxy run                               # Start + launch Claude Code

# Subscription management
clco-proxy subscription login <provider>     # Login (chatgpt, gemini, copilot)
clco-proxy subscription status               # Show all subscription status
clco-proxy subscription logout <provider>    # Remove stored credentials

# Model management
clco-proxy subscription models <provider>    # List available models
clco-proxy subscription set-model <provider> <tier> [model]  # Set model for tier
clco-proxy subscription refresh [provider]   # Refresh model cache

# Environment
clco-proxy restore                           # Restore original Claude Code settings

🧠 Smart Model Mapping

Claude Code requests models by tier name (opus, sonnet, haiku). clco-proxy maps those tiers to actual models from your configured provider.

Static mapping

// Always use gemini-2.5-pro for opus tier
"modelMapping": {
  "opus": { "provider": "gemini", "model": "gemini-2.5-pro" }
}

Auto-detect with @auto

Use @auto to let clco-proxy find the best model automatically. It queries the provider API, picks the best match, and caches the result for 24 hours.

# Set opus tier to auto-detect best "pro" model from Gemini
clco-proxy subscription set-model gemini opus @auto:pro

When a request comes in:

clco-proxy subscription set-model gemini opus @auto:pro
  → "@auto:pro" stored in config

Request: Claude Code → opus model
  → resolveModel("@auto:pro", "gemini", "opus")
  → model-cache.json lookup
  → gemini-3.1-pro-preview (auto-detected)

When a new model drops:
  clco-proxy subscription refresh gemini
  → Cache updated → next request auto-uses new model

Background refresh runs automatically on server boot, so your @auto models stay current.

🏗️ Architecture

src/
├── server/                    # Fastify HTTP server
│   ├── middleware/             # Auth, error handler
│   ├── routes/                # /v1/messages, /v1/models, /v1/messages/count_tokens
│   └── sse/                   # SSE encoder, decoder, validator
├── proxy/                     # Passthrough adapter (undici-based)
├── providers/                 # 42 per-provider adapters
├── translator/                # Anthropic ↔ OpenAI format translation
│   ├── request.ts             # Request body translation
│   ├── stream.ts              # SSE stream translation
│   ├── responses-request.ts   # Responses API request translation
│   └── responses-stream.ts    # Responses API stream translation
├── routing/                   # Model mapper + provider router
├── subscription/              # Subscription auth + model cache
│   ├── auth/                  # OAuth, Device Flow, Gemini tier detection
│   ├── stealth/               # Provider-specific stealth headers
│   ├── model-cache.ts         # 24h TTL cache + @auto resolution
│   └── background-refresh.ts  # Boot-time auto refresh
├── config/                    # Config loader, validator, defaults
├── cli/                       # CLI (Commander)
│   ├── subscription-setup.ts  # Interactive subscription login
│   ├── model-management.ts    # Models, set-model, refresh commands
│   └── env-backup.ts          # Claude env backup/restore
├── types/                     # TypeScript type definitions
└── schemas/                   # Zod validation schemas

Tech Stack

Stats: 126 TypeScript source files, 18 test files, 517 passing tests.

⚙️ Configuration

Config file: ~/.clco-proxy/config.json

Full example with multiple providers

{
  "port": 8080,
  "providers": [
    {
      "id": "gemini",
      "name": "Gemini",
      "apiKey": "AIza...",
      "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai",
      "models": ["gemini-2.5-pro", "gemini-2.5-flash"]
    },
    {
      "id": "deepseek",
      "name": "DeepSeek",
      "apiKey": "sk-...",
      "baseUrl": "https://api.deepseek.com/anthropic",
      "anthropicCompat": true
    },
    {
      "id": "ollama",
      "name": "Ollama (local)",
      "baseUrl": "http://localhost:11434/v1",
      "models": ["qwen3:32b", "devstral:24b"]
    }
  ],
  "modelMapping": {
    "opus": { "provider": "gemini", "model": "@auto:pro" },
    "sonnet": { "provider": "gemini", "model": "@auto:flash" },
    "haiku": { "provider": "deepseek", "model": "deepseek-v4-flash" },
    "default": { "provider": "gemini", "model": "@auto" }
  }
}

Key config fields

License

MIT

clco-proxy

Claude Code를 위한 Anthropic 호환 멀티 프로바이더 LLM 프록시입니다. 비싼 Claude 구독 대신 42개 이상의 프로바이더에서 저렴한 모델을 사용하세요.

                          clco-proxy
                        ┌──────────────┐
  Claude Code ──────────►              ├──── 모드 A ──── DeepSeek / GLM / Kimi ...
  (Anthropic API와 통신   │   localhost   │                (Anthropic 패스스루)
   한다고 생각함)          │   :8080      │
                         │              ├──── 모드 B ──── Gemini / GPT / Groq ...
  ANTHROPIC_BASE_URL ───►              │                (OpenAI 변환)
                         └──────────────┘

프록시가 Claude Code와 선택한 LLM 프로바이더 사이에서 API 호출을 실시간으로 변환합니다. Claude Code는 Anthropic API와 통신한다고 생각하지만, 실제로는 설정한 프로바이더를 사용합니다.

View English docs

✨ 주요 기능

• 42개 이상 LLM 프로바이더 — DeepSeek, Gemini, GPT-5.5, Groq, OpenRouter, Ollama 등
• 두 가지 변환 모드 — Anthropic 네이티브 패스스루 또는 OpenAI 포맷 전체 변환
• 구독 스텔스 — 기존 ChatGPT Plus, Gemini Ultra, GitHub Copilot 구독을 Claude Code에서 사용
• 스마트 모델 매핑 — Claude의 opus/sonnet/haiku 티어를 최적의 모델에 자동 매핑
• 자동 모델 감지 — @auto 마커가 프로바이더 API에서 최적 모델을 자동 감지, 24시간 TTL 캐시
• 백그라운드 캐시 갱신 — 서버 부팅 시 모든 프로바이더의 모델 캐시를 자동 갱신
• 환경 백업/복원 — clco-proxy run이 기존 Claude 설정을 백업, clco-proxy restore로 복원
• 전체 스트리밍 + 도구 사용 — SSE 스트리밍, ping keepalive, 함수 호출 라이프사이클 완벽 지원

🚀 빠른 시작

필수 조건: Bun >= 1.0

# 1. 설정 초기화 (대화형 설정 마법사)
npx clco-proxy config init

# 2. 프록시 데몬 시작
clco-proxy start

# 3. 프록시를 통해 Claude Code 실행
clco-proxy run

설정 파일은 ~/.clco-proxy/config.json에 저장됩니다. DeepSeek를 Anthropic 호환 모드로 사용하는 최소 설정 예시:

{
  "port": 8080,
  "providers": [
    {
      "id": "deepseek",
      "name": "DeepSeek",
      "apiKey": "sk-your-key",
      "baseUrl": "https://api.deepseek.com/anthropic",
      "models": ["deepseek-v4-flash", "deepseek-v4-pro"],
      "anthropicCompat": true
    }
  ],
  "modelMapping": {
    "opus": { "provider": "deepseek", "model": "deepseek-v4-pro" },
    "sonnet": { "provider": "deepseek", "model": "deepseek-v4-flash" },
    "haiku": { "provider": "deepseek", "model": "deepseek-v4-flash" },
    "default": { "provider": "deepseek", "model": "deepseek-v4-flash" }
  }
}

🔌 지원 프로바이더

모드 A — Anthropic 네이티브 패스스루

변환 오버헤드 없이 Anthropic API를 네이티브로 지원하는 프로바이더입니다.

모드 B — OpenAI 호환 변환

스트리밍과 도구 사용을 포함한 Anthropic-OpenAI 포맷 전체 변환.

💳 구독 스텔스

기존 유료 구독을 Claude Code에서 사용할 수 있습니다. 토큰당 요금이 부과되지 않습니다.

# 구독 프로바이더 로그인
clco-proxy subscription login chatgpt    # Codex CLI에서 OAuth 자동 감지
clco-proxy subscription login gemini     # Google AI Studio API 키 → 티어 자동 감지
clco-proxy subscription login copilot    # 브라우저에서 디바이스 플로우 OAuth

Gemini Ultra: Google AI Studio에서 무료 API 키를 발급받아 사용합니다. Google AI Ultra 구독($249.99/월) 계정으로 만든 API 키는 더 많은 모델(예: gemini-3.1-pro-preview)을 자동으로 잠금 해제합니다. clco-proxy가 구독 티어를 자동 감지하여 최적의 모델을 선택합니다.

📖 CLI 명령어

# 설정
clco-proxy config init                       # 대화형 설정 마법사
clco-proxy config show                       # 현재 설정 출력

# 데몬 관리
clco-proxy start                             # 프록시 데몬 시작
clco-proxy stop                              # 데몬 중지
clco-proxy status                            # 데몬 상태 확인
clco-proxy run                               # 시작 + Claude Code 실행

# 구독 관리
clco-proxy subscription login <provider>     # 로그인 (chatgpt, gemini, copilot)
clco-proxy subscription status               # 모든 구독 상태 표시
clco-proxy subscription logout <provider>    # 저장된 자격 증명 제거

# 모델 관리
clco-proxy subscription models <provider>    # 사용 가능한 모델 목록
clco-proxy subscription set-model <provider> <tier> [model]  # 티어별 모델 설정
clco-proxy subscription refresh [provider]   # 모델 캐시 갱신

# 환경
clco-proxy restore                           # 원래 Claude Code 설정 복원

🧠 스마트 모델 매핑

Claude Code는 티어 이름(opus, sonnet, haiku)으로 모델을 요청합니다. clco-proxy가 이 티어를 실제 모델에 매핑합니다.

정적 매핑

// 항상 gemini-2.5-pro를 opus 티어에 사용
"modelMapping": {
  "opus": { "provider": "gemini", "model": "gemini-2.5-pro" }
}

@auto로 자동 감지

@auto를 사용하면 clco-proxy가 최적의 모델을 자동으로 찾습니다. 프로바이더 API를 조회하여 최적의 매치를 선택하고 24시간 캐시합니다.

# opus 티어를 Gemini에서 최적의 "pro" 모델로 자동 감지
clco-proxy subscription set-model gemini opus @auto:pro

요청 처리 흐름:

clco-proxy subscription set-model gemini opus @auto:pro
  → "@auto:pro"가 설정에 저장됨

요청: Claude Code → opus 모델
  → resolveModel("@auto:pro", "gemini", "opus")
  → model-cache.json 조회
  → gemini-3.1-pro-preview (자동 감지됨)

새 모델이 출시되면:
  clco-proxy subscription refresh gemini
  → 캐시 갱신 → 다음 요청에서 새 모델 자동 사용

백그라운드 갱신은 서버 부팅 시 자동으로 실행되므로 @auto 모델이 항상 최신 상태를 유지합니다.

🏗️ 아키텍처

src/
├── server/                    # Fastify HTTP 서버
│   ├── middleware/             # 인증, 에러 핸들러
│   ├── routes/                # /v1/messages, /v1/models, /v1/messages/count_tokens
│   └── sse/                   # SSE 인코더, 디코더, 밸리데이터
├── proxy/                     # 패스스루 어댑터 (undici 기반)
├── providers/                 # 42개 프로바이더별 어댑터
├── translator/                # Anthropic ↔ OpenAI 포맷 변환
│   ├── request.ts             # 요청 본문 변환
│   ├── stream.ts              # SSE 스트림 변환
│   ├── responses-request.ts   # Responses API 요청 변환
│   └── responses-stream.ts    # Responses API 스트림 변환
├── routing/                   # 모델 매퍼 + 프로바이더 라우터
├── subscription/              # 구독 인증 + 모델 캐시
│   ├── auth/                  # OAuth, 디바이스 플로우, Gemini 티어 감지
│   ├── stealth/               # 프로바이더별 스텔스 헤더
│   ├── model-cache.ts         # 24시간 TTL 캐시 + @auto 해석
│   └── background-refresh.ts  # 부팅 시 자동 갱신
├── config/                    # 설정 로더, 밸리데이터, 기본값
├── cli/                       # CLI (Commander)
│   ├── subscription-setup.ts  # 대화형 구독 로그인
│   ├── model-management.ts    # 모델, set-model, refresh 명령어
│   └── env-backup.ts          # Claude 환경 백업/복원
├── types/                     # TypeScript 타입 정의
└── schemas/                   # Zod 검증 스키마

기술 스택

통계: TypeScript 소스 파일 126개, 테스트 파일 18개, 517개 테스트 통과.

⚙️ 설정

설정 파일: ~/.clco-proxy/config.json

여러 프로바이더를 사용하는 전체 예시

{
  "port": 8080,
  "providers": [
    {
      "id": "gemini",
      "name": "Gemini",
      "apiKey": "AIza...",
      "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai",
      "models": ["gemini-2.5-pro", "gemini-2.5-flash"]
    },
    {
      "id": "deepseek",
      "name": "DeepSeek",
      "apiKey": "sk-...",
      "baseUrl": "https://api.deepseek.com/anthropic",
      "anthropicCompat": true
    },
    {
      "id": "ollama",
      "name": "Ollama (local)",
      "baseUrl": "http://localhost:11434/v1",
      "models": ["qwen3:32b", "devstral:24b"]
    }
  ],
  "modelMapping": {
    "opus": { "provider": "gemini", "model": "@auto:pro" },
    "sonnet": { "provider": "gemini", "model": "@auto:flash" },
    "haiku": { "provider": "deepseek", "model": "deepseek-v4-flash" },
    "default": { "provider": "gemini", "model": "@auto" }
  }
}

주요 설정 필드

라이선스

MIT