Finesssee/ProxyPilot

API 키를 번갈아 가며 사용할 필요가 없습니다. ProxyPilot은 기존의 Claude Code, Codex, Gemini, Kiro, Qwen 구독을 별도의 API 키 없이도 모든 AI 코딩 도구에서 사용할 수 있게 해주는 강력한 로컬 API 프록시 (Proxy)입니다.

Go 언어로 구축되었으며, OAuth 인증, 토큰 관리 (Token management), API 변환 (API translation)을 자동으로 처리합니다. 하나의 서버로 이 모든 것을 라우팅하세요.

팁

📣 지원되는 최신 모델:
Claude Opus 4.5 / Sonnet 4.5 (확장된 사고 기능 포함), GPT-5.2 / GPT-5.2 Codex, Gemini 3 Pro/Flash, 그리고 Kiro (AWS CodeWhisperer)! 🚀

설정 가이드:

🎯
10개의 인증 제공자 (Auth Providers)- Claude, Codex (OpenAI), Gemini, Gemini CLI, Kiro (AWS), Amazon Q CLI, Qwen, Antigravity, MiniMax, Zhipu AI - 🔄
범용 API 변환 (Universal API Translation)- OpenAI, Anthropic, Gemini 형식 간 자동 변환 - 🔧
도구 호출 복구 (Tool Calling Repair)- 제공자 간의 도구/함수 호출 (Tool/function call) 불일치를 자동으로 수정 - 🧠
확장된 사고 (Extended Thinking)- Claude 및 Gemini 사고 모델 (Thinking models) 완전 지원 - 🔐
OAuth 통합 (OAuth Integration)- 자동 토큰 갱신을 포함한 브라우저 기반 로그인 - 👥
다중 계정 지원 (Multi-Account Support)- 자동 장애 조치 (Failover)를 포함한 라운드 로빈 (Round-robin) 분산 - ⚡
할당량 자동 전환 (Quota Auto-Switch)- 할당량 초과 시 백업 프로젝트/모델로 자동 전환 - 📊
사용 통계 (Usage Statistics)- 제공자/모델별 요청, 토큰 및 오류 추적 - 🧩
컨텍스트 압축 (Context Compression)- 긴 세션을 위한 LLM 기반 요약 (Factory.ai 연구 결과) - 🤖
에이전틱 하네스 (Agentic Harness)- 코딩 에이전트를 위한 가이드 워크플로우 (Anthropic 연구 결과) - 💾
세션 메모리 (Session Memory)- 대화 턴 간의 지속적인 저장 - 🎨
시스템 트레이 (System Tray)- 빠른 액세스를 위한 네이티브 Windows 트레이 앱 - 🔄
자동 업데이트 (Auto-Updates)- 원클릭 설치를 포함한 백그라운드 업데이트 확인 - ⏪
롤백 지원 (Rollback Support)- 버전 복구를 포함한 자동 충돌 감지 - 📡
60개 이상의 관리 API (Management APIs)- REST 엔드포인트를 통한 완전한 제어

제공자 (Provider)	인증 방식 (Auth Method)	모델 (Models)
Claude (Anthropic)	OAuth2 / API Key	Claude Opus 4.5, Sonnet 4.5, Haiku 4.5
...

계정 위험 경고: Claude/Anthropic OAuth, Google/Gemini OAuth, Gemini CLI OAuth, 그리고 Antigravity OAuth는 비공식 호환 경로입니다. 제공자(Providers)는 프록시(proxy), 자동화(automation), 공유 토큰(shared-token) 또는 제3자 OAuth 트래픽을 정책 위반 또는 비정상적인 사용으로 간주할 수 있습니다. 이러한 로그인 흐름을 사용하면 할당량(quota) 손실, 계정 제한 또는 계정 정지의 위험이 있습니다. 중요한 계정에는 공식 API 키 또는 공식적으로 지원되는 개발자 액세스를 사용하는 것을 권장합니다.

Releases 페이지로 이동하여 사용 중인 플랫폼에 맞는 최신 바이너리(binary)를 다운로드하세요.
./proxypilot을 실행하세요.

git clone https://github.com/Finesssee/ProxyPilot.git
cd ProxyPilot
go build -o proxypilot ./cmd/server
...

패키지 설치 방식은 실행 파일 옆에 config.example.yaml이 포함되어 있는 경우, 첫 실행 시 config.yaml을 자동으로 생성합니다.
소스 코드에서 실행하는 경우, 설정을 복사하세요:
cp config.example.yaml config.yaml
실행: ./proxypilot
서버는 http://localhost:8317에서 시작됩니다.
대시보드 열기: http://localhost:8317/management.html

제공자에 대한 OAuth 로그인을 실행하세요:

# OAuth 제공자 (브라우저를 엽니다)
./proxypilot --claude-login # Claude
./proxypilot --codex-login # OpenAI/Codex
...

OAuth 토큰은 로컬에 저장되며 만료 전에 자동으로 갱신(auto-refreshed)됩니다.

고위험 OAuth 제공자: --claude-login, --login (Gemini), Gemini CLI OAuth, 그리고 --antigravity-login은 제공자의 기대 사항을 위반하거나 어뷰징 방지/계정 보호 시스템을 트리거할 수 있습니다. 계정 위험에 따른 트레이드오프(tradeoff)를 수용하지 않는 한, 운영 환경(production), 결제 관련 중요 계정, 학교/직장 계정 또는 대체 불가능한 개인 계정에는 이러한 흐름을 사용하지 마십시오. 사용 가능한 경우 공식 API 키를 우선적으로 사용하십시오.

Kiro Google/GitHub OAuth는 AWS Cognito가 제3자 localhost 콜백(callback)을 거부하기 때문에 현재 지원되지 않습니다. AWS Builder ID (--kiro-login / --kiro-aws-login)를 사용하거나 공식 Kiro IDE에서 가져오기(import)를 사용하세요.

프록시 요청(Proxy requests)은 기본적으로 API 키를 요구합니다. 인증되지 않은 액세스(권장하지 않음)를 허용하려면 config.yaml에서 allow-unauthenticated: true를 설정하세요.
CORS는 기본적으로 관리용이 아닌 엔드포인트(non-management endpoints)에 대해 활성화되어 있습니다(와일드카드 *). 관리용 엔드포인트(Management endpoints)는 cors.management-allow-origins 아래에 오리진(origins)을 명시적으로 허용하지 않는 한 CORS 헤더를 발생시키지 않습니다.

예시:

allow-unauthenticated: false
cors:
  allow-origins:
    ...

Claude Code (~/.claude/settings.json):

{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8317",
...

Codex CLI (~/.codex/config.toml):

[openai]
api_base_url = "http://127.0.0.1:8317"

Factory Droid (~/.factory/settings.json):

{
"customModels": [{
"name": "ProxyPilot",
...

POST /v1/chat/completions # OpenAI Chat Completions
POST /v1/responses # OpenAI Responses API
POST /v1/messages # Anthropic Messages API
...

모든 엔드포인트는 대상 제공자(target provider)에 따라 형식을 자동으로 변환(auto-translate)합니다.

ProxyPilot은 지연 시간(latency)과 토큰 사용량을 줄이기 위해 두 가지 캐싱 계층(caching layers)을 포함합니다.

동일한 요청에 대해 전체 API 응답을 캐싱합니다. 개발 중 반복되는 쿼리에 유용합니다.

설정 (Config) (config.yaml):

response-cache:
  enabled: true # 기본값: false
  max-size: 1000 # 최대 항목 수 (기본값: 1000)
  ...

네이티브 지원이 없는 제공자를 위한 합성 프롬프트 캐싱(Synthetic prompt caching)입니다. 반복되는 시스템 프롬프트(system prompts)를 추적하고 토큰 절감량을 추정합니다.

설정 (Config) (config.yaml):

prompt-cache:
  enabled: true # 기본값: false
  max-size: 500 # 최대 항목 수 (기본값: 500)
  ...

엔드포인트 (Endpoint)	메서드 (Method)	설명 (Description)
`/v0/management/cache/stats`	GET	응답 캐시 통계 (hits, misses, size)
`/v0/management/cache/clear`	POST	응답 캐시 삭제
`/v0/management/cache/enabled`	PUT	런타임 시 활성화/비활성화 `{"enabled": true}`
`/v0/management/prompt-cache/stats`	GET	프롬프트 캐시 통계 + 예상 절약 토큰 수
`/v0/management/prompt-cache/clear`	POST	프롬프트 캐시 삭제
`/v0/management/prompt-cache/enabled`	PUT	런타임 시 활성화/비활성화
`/v0/management/prompt-cache/top`	GET	가장 많이 호출된 상위 10개 프롬프트

메모리가 적거나 높은 처리량 (high-throughput)이 필요한 설정의 경우, 더 무거운 기능들을 비활성화할 수 있습니다:

commercial-mode: true
usage-statistics-enabled: false
usage-sample-rate: 0.25
...

CLIProxyAPI를 위한 독립형 지속성 (persistence) 및 시각화 서비스로, 주기적인 데이터 동기화, SQLite 저장소, 집계 API (aggregate APIs), 그리고 사용량 및 통계를 위한 내장 대시보드를 제공합니다.

참고

CLIProxyAPI를 기반으로 프로젝트를 개발하셨다면, 이 목록에 추가할 수 있도록 PR (Pull Request)을 열어주세요.

ProxyPilot은 새로운 릴리스를 확인하고 클릭 한 번으로 설치할 수 있는 내장 자동 업데이트 시스템을 포함하고 있습니다.

설정 (Config) (config.yaml):

updates:
auto-check: true # 백그라운드 업데이트 확인 활성화 (기본값: true)
check-interval-hours: 24 # 확인 주기 (기본값: 24)
...

백그라운드 폴링 (Background Polling) - 설정 가능한 간격으로 업데이트 확인
대시보드 배너 (Dashboard Banner) - 업데이트 가능 시 선제적 알림
원클릭 설치 (One-Click Install) - 트레이 메뉴에서 다운로드, 검증 및 설치
세션 종료 (Session Dismissal) - 닫은 배너는 다음 세션 전까지 다시 나타나지 않음

업데이트가 가능할 때:

설정 (Settings) → vX.X.X 다운로드 및 설치 (Download & Install) - 원클릭 업데이트 흐름
설정 (Settings) → 업데이트 확인 (Check for Updates) - 수동 확인

ProxyPilot은 업데이트 중에 이전 버전을 자동으로 백업하며, 문제가 발생할 경우 이를 복구할 수 있습니다.

Crash Detection (충돌 감지)

30초 이내의 급격한 재시작을 추적함
Auto-Rollback (자동 롤백)
3회의 급격한 실패 발생 후, 이전 버전을 자동으로 복구함
Health Marking (상태 표시)
30초 동안 안정적으로 작동하면 실패 카운터를 초기화함

트레이 메뉴에서:

Settings (설정) → Rollback to Previous Version (이전 버전으로 롤백)

이전 버전을 복구함
업데이트 중, 현재 바이너리(binary)는 .old로 저장됨
백업 - 롤백 메타데이터는 %APPDATA%/ProxyPilot/updates/에 저장됨
충돌 루프(crash loop) 감지 시, 이전 버전이 자동으로 복구됨
성공적인 시작(30초) 이후, 백업은 정리될 수 있음

바이너리 (Binary)	설명
`proxypilot`	서버 및 설정 전환 기능을 갖춘 메인 CLI
`proxypilot-tray`	시스템 트레이 앱

다음 AI 코딩 도구들과 함께 작동합니다:

Claude Code- settings.json을 통해 자동 설정
Codex CLI- config.toml을 통해 자동 설정
Factory Droid- settings.json을 통해 자동 설정
Cursor IDE- 수동 엔드포인트(endpoint) 설정
Continue- 수동 엔드포인트(endpoint) 설정

macOS, Linux, 또는 Windows
Go 1.24+ (소스 코드 빌드용)

ProxyPilot은 @Finesssee에 의해 개발 및 유지 관리됩니다. git 히스토리에 표시된 일부 기여자들은 상위 프로젝트인 CLIProxyAPI의 병합(merges)에서 온 분들입니다. ProxyPilot의 직접적인 기여자들은 프로젝트가 성장함에 따라 여기에 나열될 것입니다.

ProxyPilot은 오픈 소스 커뮤니티의 훌륭한 작업물을 기반으로 구축되었습니다:

CLIProxyAPI- 이 프로젝트에 영감을 준 독창적인 통합 프록시 서버
VibeProxy- 깔끔한 프록시 UX를 보여주는 네이티브 macOS 메뉴 바 앱

롱 컨텍스트(Long-context) 기능은 AI 커뮤니티의 연구에서 영감을 받았습니다:

Factory.ai- 장시간 실행되는 코딩 에이전트를 위한 컨텍스트 압축 기술
Anthropic- 장시간 실행되는 에이전트를 위한 효과적인 하네스(harnesses)

자신들의 작업물과 통찰력을 공유해 준 팀들에게 특별한 감사를 전합니다.

MIT License - 자세한 내용은 LICENSE를 참조하세요.

Report Issues (이슈 보고): GitHub Issues

이 프로젝트는 교육 및 상호 운용성 연구 목적으로 제작되었습니다. 호환성 레이어(compatibility layers)를 제공하기 위해 다양한 API와 상호작용합니다.

사용 시 발생하는 위험은 사용자 본인에게 있습니다. 저자들은 계정 정지 또는 서비스 중단에 대해 책임을 지지 않습니다. Google, OpenAI, Anthropic, Amazon 또는 기타 어떤 제공업체와도 관련이 없습니다. - 사용자는 연결된 플랫폼의 서비스 약관(Terms of Service)을 준수해야 합니다.

Finesssee/ProxyPilot

요약

핵심 포인트

댓글