필요한 것
- 키 페이지의 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 관련 429 | 8개 이상의 동시 요청 (체험판 기준 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% 보너스가 적용된 더 큰 충전액이 잔액에 시간 제한을 두지 않습니다.
