KO ▾

홈가이드

OpenAI 호환 API로 Claude Code 프록시 설정

이 claude code 프록시 설정은 키 얻기, LiteLLM 구성 작성, 프록시 시작, 두 환경 변수 설정, 테스트 실행 등 5단계로 이루어집니다. 약 10분이 소요됩니다.

터미널에서 서버로 이어지는 다섯 개의 빛나는 발판, 단계별 프록시 설정을 보여줍니다

주요 포인트

  1. https://api.claudecodeproxyapi.com/v1로 포워딩하는 로컬 LiteLLM 프록시 실행
  2. ANTHROPIC_BASE_URL 및 ANTHROPIC_AUTH_TOKEN으로 Claude Code를 프록시에 연결
  3. Claude Code가 보내는 모델 이름을 업스트림 모델 uncensored로 매핑
  4. CLI 시작 전 curl로 프록시 테스트

필요한 것

  • 키 페이지의 API 키입니다. Google 또는 이메일과 비밀번호로 가입한 후 한 번의 클릭으로 $0.50 트라이얼 크레딧을 받으세요.
  • 프록시를 설치하기 위한 Python 3.9 이상
  • Claude Code가 머신에 설치되어 작동 중입니다.

왜 프록시가 필요할까요? Claude Code는 Anthropic Messages 형식을 사용하고, 당사 API는 모델 ID uncensored와 함께 OpenAI Chat Completions 형식을 사용합니다. 프록시는 두 형식 간에 번역합니다. 배경 지식이 필요하면 프록시 문제 해결 가이드를 읽으세요. 이 모델은 Claude가 아닌 오픈 웨이트 모델이므로 복잡한 다단계 작업에서 다른 동작이 예상됩니다.

1단계: 프록시 설치

가상 환경을 사용하여 프록시의 종속성이 프로젝트와 분리되도록 하세요:

python3 -m venv ~/litellm-env
source ~/litellm-env/bin/activate
pip install 'litellm[proxy]'

LiteLLM은 서드파티 오픈 소스 소프트웨어입니다. 아래 명령어 및 구성 키는 작성 시점의 공식 문서와 일치하지만, 플래그가 변경된 경우 최신 문서를 확인하세요.

2단계: 구성 작성

config.yaml을 만드세요. model_name은 클라이언트가 전송하는 이름입니다. litellm_params 블록은 이를 어디로 포워딩할지 지정합니다. openai/ 접두사는 LiteLLM이 OpenAI 호환 서버와 통신하도록 알려줍니다.

cat > config.yaml <<'EOF'
model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: openai/uncensored
      api_base: https://api.claudecodeproxyapi.com/v1
      api_key: os.environ/UPSTREAM_KEY
EOF

별칭 claude-sonnet은 예시일 뿐 필수 사항은 아닙니다. Claude Code는 기본 모델과 배경 작업용 작은 모델 등 여러 다른 모델 이름을 보낼 수 있습니다. 프록시 로그에 나타나는 각 이름에 대해 하나씩 model_list 항목을 추가하고 모두 동일한 업스트림을 가리키게 하세요. 하나의 모델만 있으므로 모든 별칭을 uncensored에 연결해도 괜찮습니다.

키는 환경 변수에서 읽으므로 파일에 저장되지 않습니다.

3단계: 프록시 시작

export UPSTREAM_KEY="YOUR_KEY"
litellm --config config.yaml --port 4000

이 터미널을 열어 두세요. 포트 4000에서 서버가 수신 대기하는 것을 확인해야 합니다. 이제 Anthropic 형식(Claude Code가 보낼 형식)으로 테스트 요청을 보내 프록시 측면에서 업스트림 경로를 확인하세요:

curl http://localhost:4000/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: sk-local-anything" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet",
    "max_tokens": 200,
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

내용에 "ready"라는 단어가 포함된 JSON 응답은 번역이 끝까지 작동함을 의미합니다: Anthropic 형식 입력 → OpenAI 형식 https://api.claudecodeproxyapi.com/v1 출력 → 다시 변환. LiteLLM 구성에 마스터 키를 설정한 경우 sk-local-anything 대신 해당 키를 사용하세요.

4단계: Claude Code를 프록시에 연결

Claude Code는 API 주소와 토큰을 환경 변수에서 읽습니다. CLI를 시작하는 셸에서 이를 설정하세요:

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local-anything"
export ANTHROPIC_MODEL="claude-sonnet"
claude

여기서는 CLI가 자체 경로를 추가하므로 프록시 주소에 /v1 접미사를 붙이지 마세요. 토큰은 프록시만 만족하면 되므로 실제 업스트림 키는 UPSTREAM_KEY로 내보낸 키입니다. 셸 대신 CLI 설정 파일을 환경 값에 사용하는 경우 동일한 세 가지 이름을 해당 파일에 넣으세요. Claude Code의 환경 변수 이름은 릴리스 간에 변경될 수 있으므로 무시되는 경우 최신 Claude Code 문서에서 확인하세요.

5단계: 첫 작업 실행 및 로그 확인

작게 시작하세요. CLI에 파일 하나를 설명하거나 함수에 주석을 추가하도록 요청하세요. 프록시 터미널에서는 단계별로 요청이 표시됩니다. 나타나는 각 모델 이름을 확인하세요. model_list에 없는 경우 프록시가 오류를 반환하므로 해당 이름을 추가하고 다시 시작하세요.

여기서 도구 호출이 중요합니다. CLI는 도구를 통해 파일을 읽고 코드를 수정합니다. API는 tools, tool_choice 및 스트리밍 tool_calls을 지원하며 프록시가 이를 변환합니다. 도구 스키마에 대한 준수도가 낮으면 편집 실패 또는 반복 단계가 나타납니다. 이 경우 설정이 깨진 것으로 결론 내리기 전에 작업을 줄이고 다시 시도하세요.

컨텍스트 창은 프롬프트와 응답을 합쳐 100,000 토큰입니다. 이를 초과하는 긴 세션은 실패하므로 새 작업에 대해 새 세션을 시작하세요. 비용은 입력 토큰 1M당 $0.15, 출력 토큰 1M당 $0.50으로 매우 낮습니다: 입력 20,000 토큰, 출력 800 토큰 요청은 $0.003 + $0.0004 = $0.0034가 듭니다. 충전 방법은 가격 책정 페이지를 확인하세요. 이 사이트에서는 암호화폐(TRC20의 USDT 또는 Base의 USDC)로 결제할 수 있습니다.

문제 해결

표시되는 내용원인해결 방법
연결 거부됨프록시가 실행 중이 아니거나 포트가 다름시작하고 ANTHROPIC_BASE_URL의 포트와 일치시킴
프록시 404 또는 "모델을 찾을 수 없음"CLI가 보낸 모델 이름이 구성에 없음해당 이름을 model_list에 추가
업스트림 401잘못되거나 비어 있는 UPSTREAM_KEY프록시 셸에서 키를 다시 내보내고 다시 시작
concurrency 관련 4298개 이상의 동시 요청 (체험판 기준 2개)동시 에이전트 수 줄이기
rate_limited과 함께 429분당 300개 이상의 요청 (체험판 기준 60개)잠시 후 재시도하세요.
429 및 Retry-After: 5일시적 과부하5초 후 재시도
스트림 지연스트리밍 요청은 종료될 때까지 슬롯을 보유함CLI에서 취소하여 슬롯 해제

여기서 다루지 않은 사항에 대해서는 지원팀에 문의할 때 X-Request-Id 응답 헤더를 포함하세요. 문서에는 지원되는 모든 매개변수가 나열되어 있습니다.

영구 설정

매번 export를 입력하는 것은 지루합니다. 프록시 시작 명령을 작은 스크립트에 넣고 클라이언트 변수를 별칭에 넣으면 한 번의 명령으로 모든 것을 시작할 수 있습니다:

cat > ~/start-proxy.sh <<'EOF'
. ~/litellm-env/bin/activate
export UPSTREAM_KEY="YOUR_KEY"
exec litellm --config ~/config.yaml --port 4000
EOF
chmod +x ~/start-proxy.sh

alias claude-uncensored='ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_AUTH_TOKEN=sk-local-anything ANTHROPIC_MODEL=claude-sonnet claude'

변수가 해당 명령어에만 설정되므로 일반 claude 명령어는 기본 설정으로 계속 작동합니다. 별칭을 셸 프로필에 추가하세요. 키를 포함하므로 chmod 700과 같은 파일 권한으로 스크립트를 보호하세요.

돌아가기

현재 셸에 변수를 내보낸 경우 unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL을 실행하고 CLI를 다시 시작하세요. API 측에서는 변경된 것이 없으므로 취소할 것이 없습니다.

잔액과 사용량 확인하기

API의 모든 응답에는 X-Balance-USD가 포함되어 키의 남은 크레딧을 나타냅니다. LiteLLM은 일부 설정에서 업스트림 헤더를 전달할 수 있지만, 잔액을 확인하는 가장 확실한 방법은 업스트림에 직접 가끔 호출하는 것입니다:

curl -i https://api.claudecodeproxyapi.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY" | grep -i x-balance-usd

에이전트 세션은 조용히 커집니다. 각 단계는 작동 중인 컨텍스트를 다시 전송하므로 긴 세션은 짧은 세션보다 요청당 비용이 더 듭니다. 각 작업에 대해 새 세션을 시작하면 입력이 작아지고 청구 금액이 낮아집니다. 발표된 가격(입력 1M당 $0.15, 출력 1M당 $0.50)에서 입력 50,000 토큰, 출력 1,000 토큰 요청은 50,000 x $0.15 / 1M = $0.0075 + $0.0005 = $0.008이 듭니다. 이러한 요청 20개를 하면 $0.16이 됩니다.

충전은 $20에서 $500까지 정수 단위로 진행되며, 이 사이트에서 USDT(TRC20) 또는 USDC(Base)로 결제합니다. 크레딧은 만료되지 않으므로, +5%, +10%, +15% 보너스가 적용된 더 큰 충전액이 잔액에 시간 제한을 두지 않습니다.

질문과 답변

Claude Code가 프록시에 필요한 환경 변수는 무엇입니까?

프록시 주소용 ANTHROPIC_BASE_URL과 프록시가 허용하는 토큰용 ANTHROPIC_AUTH_TOKEN입니다. ANTHROPIC_MODEL에는 정의한 별칭을 지정할 수 있습니다. 변경 사항을 확인하려면 최신 Claude Code 문서를 참조하세요.

ANTHROPIC_BASE_URL에 /v1을 붙여야 하나요?

아니요. CLI 앱이 자체 경로를 추가하므로 http://localhost:4000과 같은 프록시 주소를 사용하세요. /v1은 프록시 구성의 업스트림 api_base에만 해당됩니다.

LiteLLM 이외의 프록시를 사용할 수 있나요?

네. Anthropic Messages 요청을 OpenAI Chat Completions으로 변환하는 모든 프록시가 작동합니다. 예: claude-code-router. 업스트림을 https://api.claudecodeproxyapi.com/v1로 설정하고 모델은 uncensored를 사용하세요.

업스트림 키가 구성 파일에 안전하게 저장되나요?

위 구성 예시와 같이 파일 대신 환경 변수에 키를 저장하세요. 키를 저장소에 커밋하지 마세요.

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

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