비-Anthropic 모델과 함께 Claude Code 사용하기

LiteLLM 프록시를 통해 OpenAI, Gemini 등 비-Anthropic 모델을 Claude Code에서 사용하는 방법을 알려드릴게요.

출처: 문서

본문

info

LiteLLM은 서로 다른 제공자 형식 간에 자동으로 번역해요. 그래서 Anthropic Messages API 형식을 유지하면서도 Claude Code와 함께 어떤 지원 LLM 제공자든 사용할 수 있어요.

사전 요구 사항

Claude Code 설치
선택한 제공자(OpenAI, Vertex AI 등)의 API 키

설치

먼저 프록시 지원이 포함된 LiteLLM을 설치해요.

uv tool install 'litellm[proxy]'

구성

1. config.yaml 설정

선호하는 비-Anthropic 모델로 구성 파일을 만들어요.

OpenAI
Google AI Studio
Vertex AI
Azure OpenAI

model_list:  # OpenAI gpt-5.6-terra  - model_name: gpt-5.6-terra    litellm_params:      model: openai/gpt-5.6-terra      api_key: os.environ/OPENAI_API_KEY    # OpenAI gpt-5.6-luna  - model_name: gpt-5.6-luna    litellm_params:      model: openai/gpt-5.6-luna      api_key: os.environ/OPENAI_API_KEY

환경 변수를 설정해요.

export OPENAI_API_KEY="your-openai-api-key"export LITELLM_MASTER_KEY="sk-

"  # Generate a secure key

model_list:  # Google Gemini  - model_name: gemini-3.8-flash    litellm_params:      model: gemini/gemini-3.8-flash      api_key: os.environ/GEMINI_API_KEY

환경 변수를 설정해요.

export GEMINI_API_KEY="your-gemini-api-key"export LITELLM_MASTER_KEY="sk-

"  # Generate a secure key

model_list:  # Google Gemini  - model_name: vertex-gemini-3.8-flash    litellm_params:      model: vertex_ai/gemini-3.8-flash      vertex_credentials: os.environ/VERTEX_FILE_PATH_ENV_VAR # os.environ["VERTEX_FILE_PATH_ENV_VAR"] = "/path/to/service_account.json"       vertex_project: "my-test-project"      vertex_location: "us-east-1"  # Anthropic Claude  - model_name: anthropic-vertex    litellm_params:      model: vertex_ai/claude-sonnet-5      vertex_ai_project: "my-test-project"      vertex_ai_location: "us-east-1"      vertex_credentials: os.environ/VERTEX_FILE_PATH_ENV_VAR # os.environ["VERTEX_FILE_PATH_ENV_VAR"] = "/path/to/service_account.json"

환경 변수를 설정해요.

export VERTEX_FILE_PATH_ENV_VAR="/path/to/service_account.json"export LITELLM_MASTER_KEY="sk-

"

model_list:  # Azure OpenAI  - model_name: azure-gpt-5.6-terra    litellm_params:      model: azure/gpt-5.6-terra      api_key: os.environ/AZURE_API_KEY      api_base: os.environ/AZURE_API_BASE      api_version: "2024-02-01"

환경 변수를 설정해요.

export AZURE_API_KEY="your-azure-api-key"export AZURE_API_BASE="https://your-resource.openai.azure.com"export LITELLM_MASTER_KEY="sk-

"

2. LiteLLM Proxy 시작

litellm --config /path/to/config.yaml# RUNNING on http://0.0.0.0:4000

3. 설정 검증

프록시가 올바르게 동작하는지 테스트해 봐요.

OpenAI
Google AI Studio
Vertex AI
Azure OpenAI

curl -X POST http://0.0.0.0:4000/v1/messages \-H "Authorization: Bearer $LITEL..._KEY" \-H "Content-Type: application/json" \-d '{    "model": "gpt-5.6-terra",    "max_tokens": 1000,    "messages": [{"role": "user", "content": "What is the capital of France?"}]}'

curl -X POST http://0.0.0.0:4000/v1/messages \-H "Authorization: Bearer $LITEL..._KEY" \-H "Content-Type: application/json" \-d '{    "model": "gemini-3.8-flash",    "max_tokens": 1000,    "messages": [{"role": "user", "content": "What is the capital of France?"}]}'

curl -X POST http://0.0.0.0:4000/v1/messages \-H "Authorization: Bearer $LITEL..._KEY" \-H "Content-Type: application/json" \-d '{    "model": "gemini-3.8-flash",    "max_tokens": 1000,    "messages": [{"role": "user", "content": "What is the capital of France?"}]}'

curl -X POST http://0.0.0.0:4000/v1/messages \-H "Authorization: Bearer $LITEL..._KEY" \-H "Content-Type: application/json" \-d '{    "model": "azure-gpt-5.6-terra",    "max_tokens": 1000,    "messages": [{"role": "user", "content": "What is the capital of France?"}]}'

4. Claude Code 구성

Claude Code가 LiteLLM 프록시를 사용하도록 구성해요.

export ANTHROPIC_BASE_URL="http://0.0.0.0:4000"export ANTHROPIC_AUTH_TOKEN="$LITELLM_MASTER_KEY"

tip

LITELLM_MASTER_KEY는 Claude Code에 모든 프록시 모델에 대한 접근을 부여해요. LiteLLM UI에서 가상 키를 만들어 특정 모델로 접근을 제한할 수도 있어요.

5. 비-Anthropic 모델과 함께 Claude Code 사용

Claude Code를 시작하고 사용할 모델을 지정해요.

# Use OpenAI gpt-5.6-terraclaude --model gpt-5.6-terra# Use OpenAI gpt-5.6-luna for faster responsesclaude --model gpt-5.6-luna# Use Google Geminiclaude --model gemini-3.8-flash# Use Vertex AI Geminiclaude --model vertex-gemini-3.8-flash# Use Vertex AI Anthropic Claudeclaude --model anthropic-vertex# Use Azure OpenAIclaude --model azure-gpt-5.6-terra

6. `/model`로 런타임에서 모델 전환

Claude Code가 실행 중이면 내장 /model 명령으로 LiteLLM 프록시가 노출하는 어떤 모델로든 전환할 수 있어요. 기본적으로 선택기는 Anthropic의 하드코딩된 모델만 보여주므로, LiteLLM 프록시의 모델로 채우려면 gateway model discovery에 옵트인해야 해요.

Claude Code를 실행하기 전에 다음 환경 변수를 설정해요.

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

시작 시 Claude Code가 ANTHROPIC_BASE_URL(즉 LiteLLM 프록시)에 대해 GET /v1/models를 호출하고 반환된 각 모델을 From gateway라는 라벨로 /model 선택기에 추가해요. Claude Code 안에서 실행해요:

/model

그리고 gpt-5.6-terra, gemini-3.8-flash, anthropic-vertex 등 LiteLLM이 관리하는 어떤 모델이든 선택해 세션을 재시작하지 않고 전환할 수 있어요.

요구 사항

Claude Code v2.1.129 이상.
ANTHROPIC_BASE_URL은 Anthropic Messages API 형식을 서빙하는 게이트웨이를 가리켜야 해요. LiteLLM은 /v1/messages에서 이를 처리해요.
발견은 옵트인이에요. CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1이 없으면 Claude Code는 프록시의 /v1/models를 조회하지 않고 /model 선택기는 내장 Anthropic 모델만 보여줘요. Claude Code v2.1.247에서 확인됨: 변수가 설정된 후에만 선택기가 모델을 From gateway로 라벨링해요. ENABLE_TOOL_SEARCH처럼 .claude/settings.json의 env 블록에 영구히 둘 수 있어요.

특정 모델만 표시하기

LiteLLM 모델 중 일부만 /model 선택기에 표시하고 싶다면, 그 모델들로 범위가 지정된 가상 키를 발급해 ANTHROPIC_AUTH_TOKEN으로 사용해요. /v1/models는 키가 접근할 수 있는 모델만 반환해요.

ANTHROPIC_CUSTOM_MODEL_OPTION으로 개별 모델 엔트리를 수동으로 추가할 수도 있어요(발견 대신 또는 발견과 함께).

7. `display_name`으로 선택기에 깔끔한 이름 표시

/model 선택기는 id에 claude 또는 anthropic이 포함된 게이트웨이 모델만 유지해요. 그래서 비-Anthropic 모델은 kimi-k3-claude-compatible 같은 claude 스타일 이름이 있어야 나타나요. 그러면 선택기가 그 원래 id를 라벨로 보여줘요. 라우팅에는 id를 유지하면서 더 친근한 라벨을 보여주려면, 모델의 model_info 아래에 display_name을 설정해요.

model_list:  - model_name: kimi-k3-claude-compatible    litellm_params:      model: moonshot/kimi-k3      api_key: os.environ/MOONSHOT_API_KEY    model_info:      display_name: Kimi K3

이제 Anthropic 형태의 GET /v1/models 응답이 해당 엔트리에 "display_name": "Kimi K3"를 반환하므로, 선택기는 Kimi K3(From gateway 라벨)를 나열하면서 모든 요청은 계속 kimi-k3-claude-compatible id를 사용해요. display_name이 없는 모델은 id를 계속 보여주고, OpenAI 형태의 목록은 영향을 받지 않아요. 다른 하네스에서 중복되지 않아요.

8. 게이트웨이 모델에 보고되는 컨텍스트 창

Claude Code는 Anthropic의 모델 중 하나로 인식하지 못하는 모델 이름에 자체 기본 컨텍스트 창을 적용하고, 모든 게이트웨이 서빙 이름이 그 범주에 들어가요. 모델의 model_info 아래에 max_input_tokens를 선언하면 GET /v1/models, /model/info, LiteLLM UI가 보고하는 것을 바꾸고, 프록시 자체의 컨텍스트 창 pre-call 체크를 구동하지만, 클라이언트가 표시하는 수치나 클라이언트가 컨팩트(compact)를 하는 시점은 바꾸지 않아요.

그 쪽은 Claude Code에서 CLAUDE_CODE_AUTO_COMPACT_WINDOW 또는 .claude/settings.json의 autoCompactWindow로 설정해요. 모델 구성(model configuration) 문서를 참고하세요. 실제 창이 클라이언트가 가정하는 것보다 작은 모델이 확인할 만한 경우예요. 클라이언트가 계속 컨텍스트를 채우면 제공자가 거부하기 때문이에요. 라우터도 같은 분리를 가지며, Auto Router with Claude Code and Claude Desktop에서 다뤄요.

동작 원리

LiteLLM은 다음과 같은 통합 인터페이스 역할을 해요.

요청 수신: Claude Code에서 Anthropic Messages API 형식으로 요청을 받아요
번역: 요청을 대상 제공자의 형식(OpenAI, Gemini 등)으로 번역해요
전달: 요청을 실제 제공자로 전달해요
번역: 응답을 다시 Anthropic Messages API 형식으로 번역해요
반환: 응답을 Claude Code에 반환해요

이 덕분에 LiteLLM이 지원하는 어떤 LLM 제공자든 Claude Code의 인터페이스로 사용할 수 있어요.

고급 기능

로드 밸런싱 및 폴백

자동 폴백과 함께 여러 배포를 구성해요.

model_list:  - model_name: gpt-5.6-terra  # virtual model name    litellm_params:      model: openai/gpt-5.6-terra      api_key: os.environ/OPENAI_API_KEY    - model_name: gpt-5.6-terra  # same virtual name    litellm_params:      model: azure/gpt-5.6-terra      api_key: os.environ/AZURE_API_KEY      api_base: os.environ/AZURE_API_BASErouter_settings:  routing_strategy: simple-shuffle  # Load balance between deployments  num_retries: 2  timeout: 30

사용량 추적 및 예산

LiteLLM UI를 통해 사용량을 추적하고 예산을 설정해요.

general_settings:  master_key: os.environ/LITELLM_MASTER_KEY  database_url: "postgresql://..."  # Enable database for tracking  store_model_in_db: true

UI와 함께 프록시를 시작해요.

litellm --config /path/to/config.yaml --detailed_debug

http://0.0.0.0:4000/ui에서 UI에 접근해 다음을 할 수 있어요.

사용량 분석 보기
사용자/키별 예산 한도 설정
여러 제공자의 비용 모니터링
특정 권한을 가진 가상 키 생성

지원되는 제공자

LiteLLM은 100개 이상의 제공자를 지원해요. Claude Code와 함께 사용하기 좋은 인기 제공자는 다음과 같아요.

OpenAI: gpt-5.6-terra, gpt-5.6-luna, o1, o3-mini
Google: Gemini 3.8 Flash, Gemini 3.1 Pro
Azure OpenAI: Azure를 통한 모든 OpenAI 모델
AWS Bedrock: Llama, Mistral 등 모델
Vertex AI: Google Cloud의 Gemini, Claude 등 모델
Groq: Llama와 Mixtral의 빠른 추론
Together AI: Llama, Mixtral 등 오픈소스 모델
Deepseek: Deepseek-chat, Deepseek-coder

지원되는 전체 제공자 목록 보기 →

더 알아보기 (Learn more)

Claude Code Quickstart - 기본 Claude Code 설정
Provider Tutorials
Supported Providers

비-Anthropic 모델과 함께 Claude Code 사용하기