KO ▾

홈가이드

Claude Code 프록시: OpenAI 호환 LLM API 사용

Claude Code 프록시는 CLI와 모델 API 사이에 위치하여 요청을 번역하는 작은 서버입니다. Claude Code는 Anthropic 형식을 사용하고 이 API는 OpenAI 형식을 사용하므로 프록시가 필요합니다.

터미널과 서버 사이에 있는 번역 상자, 두 API 형식 간 요청을 변환하는 프록시 표시

주요 포인트

  1. Claude Code는 Anthropic 스타일 요청을 보내며, 이 API는 OpenAI 스타일 요청을 받습니다.
  2. LiteLLM과 같은 번역 프록시가 중간에 위치하여 모델 이름을 매핑합니다.
  3. 뒤의 모델은 Claude가 아닌 오픈 웨이트 모델이므로 자체 작업으로 테스트하세요.
  4. 입력 20,000 토큰, 출력 800 토큰인 요청 30개 코딩 세션의 비용은 약 $0.10입니다.

프록시의 역할

Claude Code 프록시는 Anthropic의 코딩 CLI와 응답하는 모델 사이에 실행하는 모든 서버입니다. Claude Code는 API 주소를 위한 환경 변수를 읽고 요청을 해당 주소로 보냅니다. 해당 주소가 프록시인 경우, 프록시가 실제 동작을 결정합니다: 트래픽을 로깅하거나 규칙을 추가하거나 다른 모델로 호출을 전달할 수 있습니다.

핵심은 와이어 포맷입니다. Claude Code는 Anthropic의 Messages 포맷을 사용합니다. https://api.claudecodeproxyapi.com/v1의 API는 모델 ID uncensored를 사용하는 OpenAI Chat Completions 포맷을 따릅니다. 두 포맷은 취지가 비슷하지만 호환되지 않으므로, Claude Code에 우리 URL을 그대로 붙여넣을 수 없습니다. 번역 레이어는 스트리밍 청크와 함수 호출을 포함해 각 요청과 응답을 다시 작성해야 합니다.

구성 요소 위치

파트사용하는 형식역할
Claude Code CLIAnthropic Messages 형식수정 계획, 도구 호출, diff 표시
번역 프록시 (로컬)두 형식 모두요청 및 스트림 변환, 모델 이름 매핑
이 APIOpenAI Chat Completions오픈 웨이트 모델 실행, 토큰당 과금

커뮤니티 프로젝트가 중간 단계를 처리합니다. LiteLLM의 프록시와 claude-code-router는 이 목적으로 공개적으로 문서화된 두 가지 예시입니다. 둘 다 서드파티 소프트웨어이므로, 이를 기반으로 빌드하기 전에 지원되는 버전과 플래그를 확인하려면 현재 문서를 참조하십시오. 프록시 문제 해결 가이드는 중간에 무언가 실패할 때 시작하기 좋은 곳이며, 이 사이트에는 별도의 단계별 설정 글도 있습니다.

설정 전: 모델에 대해 정직하게

Claude Code는 Anthropic 자체 모델을 중심으로 구축되었습니다. 다른 모델로 교체하면 동작이 변경되며, 어떤 프록시도 이를 숨길 수 없습니다. 현재 모델은 독립적인 제공업체가 운영하는 오픈 웨이트 모델 중 하나로, 합법적인 성인 사용에 대해 콘텐츠 거부 없이 응답하도록 조정되었습니다. 이는 Claude가 아니며, Anthropic 또는 기타 벤더의 공식 API가 아닙니다.

에이전트 스타일 작업에서 제공하는 것:

  • tools, tool_choice 및 스트리밍되는 tool_calls를 사용한 도구 호출이며, 결과는 role: "tool" 메시지로 반환됩니다.
  • 프롬프트와 완성 텍스트를 합쳐 100,000 토큰의 컨텍스트 창.
  • response_format을 사용한 JSON 모드와 SSE를 통한 스트리밍입니다.

직접 확인해야 할 사항: 긴 에이전트 루프를 얼마나 잘 따르는지, 잘못된 형식의 함수 호출을 얼마나 자주 생성하는지, 그리고 언어와 프레임워크를 어떻게 처리하는지입니다. 전체 워크플로우를 전환하기 전에 저장소에서 실제 작업 3~4개를 실행하세요. 가입 후 한 번의 클릭으로 받을 수 있는 $0.50 무료 체험 크레딧이면 충분합니다.

상위 API 먼저 테스트

Claude Code를 건드리기 전에 도구 호출을 포함한 일반 요청으로 API 측이 작동하는지 확인하세요. 에이전트는 이에 의존합니다:

curl https://api.claudecodeproxyapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "List the files in the src folder."}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "list_files",
        "description": "List files in a directory",
        "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

좋은 답변에는 tool_calls 항목에 list_files과 JSON 인수 문자열이 포함됩니다. 이를 확인했다면 상위 서비스가 준비된 것이므로, 이후의 문제는 프록시 또는 CLI 구성에 있습니다.

두 가지 경로 및 선택 기준

경로 1: Claude Code용 번역 프록시

Claude Code 인터페이스, 권한 프롬프트 및 워크플로우를 좋아하고 그 뒤에 다른 모델을 사용하고 싶다면 이 옵션을 선택하십시오. 프록시를 로컬에서 실행하고 CLI를 가리킨 후, CLI가 보내는 모델 이름을 uncensored에 매핑합니다. 정확한 변수는 문서 및 설정 글에서 다룹니다.

경로 2: OpenAI를 이미 지원하는 클라이언트

Aider, Continue, Cline을 포함한 여러 오픈 소스 코딩 어시스턴트 및 편집기 확장은 OpenAI 호환 엔드포인트를 직접 사용할 수 있습니다. base URL, 키 및 모델 이름을 입력하면 유지할 번역 레이어가 없습니다. Claude Code 인터페이스가 특별히 필요하지 않다면 이 경로가 더 짧고 고장 날 수 있는 부분이 적습니다.

경험칙: 코드에서의 모델에 대한 빠른 테스트를 위해 경로 2를 선택하고, 팀이 이미 Claude Code 워크플로우에 의존하고 있다면 경로 1을 선택하세요.

코딩 세션 비용

에이전트는 많은 컨텍스트를 재전송하므로 입력 토큰이 요금의 대부분을 차지합니다. 30개의 세션 요청을 예로 들어보겠습니다. 각 요청에는 파일, 기록, 함수 호출 결과 등 20,000개의 입력 토큰과 800개의 출력 토큰이 있습니다:

  • 입력: 30 x 20,000 = 600,000 토큰, 즉 0.6 x $0.15 = $0.09
  • 출력: 30 x 800 = 24,000 토큰, 즉 0.024 x $0.50 = $0.012
  • 합계: $0.102

가격은 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50입니다. 선불 크레딧에서 청구되며 구독은 없으며, 실패하거나 거부된 요청에는 요금이 부과되지 않고 크레딧은 만료되지 않습니다. 충전은 $20부터 $500까지 가능하며, $50부터 +5%, $100부터 +10%, $200부터 +15%의 보너스가 제공됩니다. 이 사이트는 암호화폐(TRC20의 USDT 또는 Base의 USDC)로 충전을 받습니다. 가격 책정 페이지에 전체 표가 있으며, 키 페이지에서 Google 또는 이메일로 가입할 수 있습니다.

에이전트 루프에 영향을 미치는 제한 사항

전체 키는 동시 요청 8개와 분당 300개의 요청을 허용합니다. 체험 키는 동시 2개, 분당 60개를 허용합니다. 하위 작업을 분산하는 에이전트는 먼저 동시성 한도에 도달할 수 있습니다. API는 이 경우 concurrency 코드로 HTTP 429를 반환하며, 요청 속도 제한은 rate_limited을 반환합니다. 일시적인 과부하 또한 429를 반환하며, Retry-After: 5 헤더가 포함됩니다. 좋은 프록시는 지연 시간 후 429에서 재시도하며, 스트리밍 요청은 스트림이 끝날 때까지 슬롯을 유지하므로, 멈춘 스트림은 사용자의 할당량에 포함됩니다.

요청 본문은 최대 8 MB까지 가능합니다. 프롬프트에 큰 파일을 붙여넣는 경우 이를 염두에 두고, 전체 프롬프트를 100,000 토큰 창 내에 유지하세요.

로컬 프록시 보안 참고사항

프록시는 업스트림 키를 보유하므로 자격 증명처럼 취급해야 합니다. 다른 기기가 프록시에 접근해야 하는 특별한 필요가 없는 한, 모든 네트워크 인터페이스가 아닌 로컬호스트에 바인딩하세요. 키를 버전 관리 시스템에 포함될 파일에 저장하기보다는 환경 변수나 시크릿 관리자에 저장하세요. 팀 내에서 프록시를 공유할 경우, 업스트림 키를 변경하지 않고도 키를 교체할 수 있도록 고유한 마스터 키를 부여하세요.

에이전트가 무엇을 보내는지도 기억하십시오. 코딩 CLI는 파일 내용, 명령 출력 및 프롬프트를 모델에 전달합니다. 프롬프트는 여기서 학습에 사용되지 않지만, 여전히 개인 키 및 .env 파일과 같은 비밀을 에이전트가 읽을 수 있는 작업 디렉토리 외부에 보관해야 합니다.

코드에서 모델을 평가하는 공정한 방법

실제 저장소에서 증가하는 난이도의 세 가지 작업을 선택하십시오: 단일 파일 수정, 세 파일에 영향을 미치는 변경, 테스트가 포함된 작은 리팩토링입니다. 동일한 프롬프트로 각 작업을 두 번 실행하십시오. 하나는 현재 모델로, 다른 하나는 uncensored로 실행합니다. 네 가지 사항에 대해 메모를 유지하십시오: 수정이 깔끔하게 적용되었는지, 도구 호출이 구문 분석되었는지, 몇 번의 재시도가 필요했는지, 각 실행의 비용은 얼마였는지. 이 작업에 1시간을 투자하면 리더보드보다 더 많은 것을 알 수 있습니다.

만약 오픈 웨이트 모델이 가장 어려운 작업에서 부족하다면, 테스트 작성, 커밋 메시지 작성 또는 낯선 코드 설명과 같은 저렴한 작업에는 여전히 적합할 수 있습니다. 선불 크레딧에서 쓴 만큼만 지불하고 구독이 없으므로, 이러한 작업에만 사용해도 패널티가 없습니다.

질문과 답변

프록시 없이 Claude Code에서 이 API를 사용할 수 있나요?

아니요. Claude Code는 Anthropic 형식의 요청을 전송하고 이 API는 OpenAI 형식의 요청을 수락하므로, 두 시스템 간에 변환 계층이 필요합니다.

모델이 Claude처럼 동작하나요?

아니요. 이 모델은 독립적인 제공업체의 오픈 웨이트 모델입니다. 이를 신뢰하기 전에 자체 작업에서 테스트하세요.

API가 도구 호출을 지원하나요?

네. 도구, tool_choice 및 스트리밍 tool_calls를 지원하며, role이 tool인 메시지로 결과를 반환합니다.

프록시보다 더 쉬운 옵션이 있나요?

네. Aider, Continue, Cline과 같이 OpenAI 호환 엔드포인트를 수락하는 코딩 어시스턴트는 base URL에 직접 연결할 수 있습니다.

시도해 보려면 비용이 얼마나 들나요?

새로운 사용자는 가입 후 한 번의 클릭으로 무료 체험 크레딧 $0.50을 받을 수 있습니다. 7일 동안 유효하며 카드가 필요하지 않습니다.

키는 양식 하나만 작성하면 받을 수 있습니다

계정을 생성하고 키를 복사한 후 base URL을 변경하세요. 설정은 이것으로 끝입니다.