Claude Code Quickstart

Claude Code Quickstart

Claude Code에서 LiteLLM 프록시를 통해 Claude 모델을 호출하는 방법을 알려드릴게요.

출처: 문서

본문

info

이 튜토리얼은 Anthropic의 공식 LiteLLM 구성 문서를 기반으로 해요. 이 통합을 통해 중앙 집중식 인증, 사용량 추적, 비용 제어와 함께 Claude Code에서 LiteLLM이 지원하는 어떤 모델이든 사용할 수 있어요.

비디오 워크스루

사전 요구 사항

  • Claude Code 설치

  • 선택한 제공자의 API 키

설치

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

uv tool install 'litellm[proxy]'

1. config.yaml 설정

환경 변수를 사용해 안전한 구성을 만들어요.

model_list:  # Configure the models you want to use  - model_name: claude-opus-4-7    litellm_params:      model: anthropic/claude-opus-4-7      api_key: os.environ/ANTHROPIC_API_KEY  - model_name: claude-sonnet-4-6    litellm_params:      model: anthropic/claude-sonnet-4-6      api_key: os.environ/ANTHROPIC_API_KEY  - model_name: claude-haiku-4-5-20251001    litellm_params:      model: anthropic/claude-haiku-4-5-20251001      api_key: os.environ/ANTHROPIC_API_KEYgeneral_settings:  master_key: os.environ/LITELLM_MASTER_KEY

환경 변수를 설정해요.

export ANTHROPIC_API_KEY="your-anthropic-api-key"export LITELLM_MASTER_KEY="sk-

"  # Generate a secure key

tip

또는 ANTHROPIC_API_KEY를 프록시 디렉터리의 .env 파일에 저장할 수도 있어요. LiteLLM이 시작할 때 자동으로 로드해요.

2. 프록시 시작

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

3. 설정 검증

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

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

4. Claude Code 구성

정적 API 키

고정 LiteLLM 키를 ANTHROPIC_AUTH_TOKEN으로 설정해요.

export ANTHROPIC_AUTH_TOKEN="$LITELLM_KEY"

tip

$LITELLM_KEY는 프록시 마스터 키 또는 가상 키일 수 있어요. 마스터 키는 Claude Code에 모든 프록시 모델에 대한 접근을 부여해요. 가상 키는 해당 키가 접근할 수 있는 모델로 제한돼요.

방법 1: 통합 엔드포인트 (권장)

Claude Code가 LiteLLM의 통합 엔드포인트를 사용하도록 구성해요.

export ANTHROPIC_BASE_URL="http://0.0.0.0:4000"

방법 2: 제공자별 패스스루 엔드포인트

또는 Anthropic 패스스루 엔드포인트를 사용해요.

export ANTHROPIC_BASE_URL="http://0.0.0.0:4000/anthropic"

헬퍼가 있는 동적 API 키

키 회전이나 사용자별 인증을 위해, Claude Code는 정적 ANTHROPIC_AUTH_TOKEN 대신 키(예: JWT)를 가져오는 스크립트를 실행할 수 있어요.

  • API 키 헬퍼 스크립트를 만들어요.
#!/bin/bash# ~/bin/get-litellm-key.sh# Example: Generate JWT tokenjwt encode \  --secret="${JWT_SECRET}" \  --exp="+1h" \  '{"user":"'${USER}'","team":"engineering"}'
  • Claude Code 설정이 헬퍼를 사용하도록 구성해요.
{  "apiKeyHelper": "~/bin/get-litellm-key.sh"}
  • 토큰 갱신 간격을 설정해요.
# Refresh every hour (3600000 ms)export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000

이 값은 Authorization과 X-Api-Key 헤더로 전송돼요. apiKeyHelper는 ANTHROPIC_AUTH_TOKEN이나 ANTHROPIC_API_KEY보다 낮은 우선순위를 가져요.

5. Claude Code 사용

사용할 모델로 Claude Code를 시작해요.

# Specify model at startup (Opus 4.7 — newest Claude Code model)claude --model claude-opus-4-7# Or specify a different modelclaude --model claude-sonnet-4-6claude --model claude-haiku-4-5-20251001# Or change model during a sessionclaude/model claude-opus-4-7

또는 환경 변수로 기본 모델을 설정해요.

export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001claude

1M 컨텍스트 창 사용

Claude Code는 [1m] 접미사를 사용한 확장 컨텍스트(1백만 토큰)를 지원해요.

# Use Opus 4.7 with 1M context (requires quotes in shell)claude --model 'claude-opus-4-7[1m]'# Inside a Claude Code session (no quotes needed)/model claude-opus-4-7[1m]

warning

중요: 셸에서 --model과 함께 [1m]을 사용할 때는 셸이 대괄호를 해석하지 않도록 따옴표를 사용해야 해요.

동작 원리:

  • Claude Code는 LiteLLM에 보내기 전에 [1m] 접미사를 제거해요

  • Claude Code가 anthropic-beta: context-1m-2025-08-07 헤더를 자동으로 추가해요

  • LiteLLM config의 모델 이름에는 [1m]이 포함되지 않아야 해요

1M 컨텍스트가 활성화됐는지 확인:

/context# Should show: 21k/1000k tokens (2%)

대화 예시:

문제 해결

흔한 문제와 해결 방법:

Claude Code가 연결되지 않는 경우:

  • 프록시가 실행 중인지 확인: curl http://0.0.0.0:4000/health

  • ANTHROPIC_BASE_URL이 올바르게 설정됐는지 확인

  • ANTHROPIC_AUTH_TOKEN이 LiteLLM 마스터 키와 일치하는지 확인

인증 오류:

  • 환경 변수가 설정됐는지 확인: echo $LITELLM_MASTER_KEY

  • API 키가 유효하고 크레딧이 충분한지 확인

  • ANTHROPIC_AUTH_TOKEN이 LiteLLM 마스터 키와 일치하는지 확인

모델을 찾을 수 없는 경우:

  • Claude Code의 모델 이름이 config.yaml과 정확히 일치하는지 확인

  • --model 플래그나 환경 변수로 모델을 지정

  • 자세한 오류 메시지는 LiteLLM 로그 확인

MCP 도구가 컨텍스트 창을 채우는 경우:

  • ANTHROPIC_BASE_URL이 퍼스트파티 Anthropic 호스트가 아니면 Claude Code는 tool search를 꺼서 /context가 loaded on-demand 대신 모든 MCP 도구 스키마를 인라인으로 보여줘요

  • ENABLE_TOOL_SEARCH=true 환경 변수를 설정해요. 이상적으로는 .claude/settings.json의 env 블록에 (Keep MCP tools out of the context window 참고)

Bedrock/Vertex AI/Azure Foundry 모델 사용

여러 제공자와 모델을 지원하도록 구성을 확장해요.

제공자를 연결하기 전에 라이브 호환성을 확인하세요

Claude Code 기능과 각 제공자(Anthropic, Bedrock, Vertex AI, Azure) 간의 호환성은 Claude Code와 LiteLLM이 업데이트를 배포하면서 바뀌어요. Claude Code × LiteLLM 호환성 매트릭스는 Haiku 4.5, Sonnet 4.6, Opus 4.7에 대해 최신 안정 LiteLLM 프록시로 매일 재생성돼요. 어떤 (feature, provider) 셀이 현재 초록색인지 먼저 확인하세요.

  • 다중 제공자 설정
model_list:  # Anthropic models  - model_name: claude-opus-4-7    litellm_params:      model: anthropic/claude-opus-4-7      api_key: os.environ/ANTHROPIC_API_KEY  - model_name: claude-sonnet-4-6    litellm_params:      model: anthropic/claude-sonnet-4-6      api_key: os.environ/ANTHROPIC_API_KEY  # AWS Bedrock (Invoke — recommended for Claude Code today, see note below)  - model_name: claude-bedrock-opus    litellm_params:      model: bedrock/invoke/us.anthropic.claude-opus-4-7      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY      aws_region_name: us-west-2  - model_name: claude-bedrock-sonnet    litellm_params:      model: bedrock/invoke/us.anthropic.claude-sonnet-4-6      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY      aws_region_name: us-west-2  - model_name: claude-bedrock-haiku    litellm_params:      model: bedrock/invoke/us.anthropic.claude-haiku-4-5-20251001-v1:0      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY      aws_region_name: us-west-2  # Azure Foundry  - model_name: claude-opus-azure    litellm_params:      model: azure_ai/claude-opus-4-7      api_key: os.environ/AZURE_AI_API_KEY      api_base: os.environ/AZURE_AI_API_BASE # https://my-resource.services.ai.azure.com/anthropic  # Google Vertex AI  - model_name: claude-opus-vertex    litellm_params:      model: vertex_ai/claude-opus-4-7      vertex_ai_project: "my-test-project"      vertex_ai_location: "us-east5"      vertex_credentials: os.environ/VERTEX_FILE_PATH_ENV_VAR # os.environ["VERTEX_FILE_PATH_ENV_VAR"] = "/path/to/service_account.json"general_settings:  master_key: os.environ/LITELLM_MASTER_KEY

코드 변경 없이 모델 사이를 전환해요.

# Use Anthropic API directly (newest Claude Code model)claude --model claude-opus-4-7# Use Bedrock deployment (Opus 4.7 via Invoke)claude --model claude-bedrock-opus# Use Azure Foundry deploymentclaude --model claude-opus-azure# Use Vertex AI deploymentclaude --model claude-opus-vertex

Claude Code를 위한 Bedrock 특화 설정

오늘 LiteLLM을 통해 Claude Code가 Bedrock에서 깔끔하게 동작하게 하려면 추가 단계 두 개가 필요해요. Bedrock 기반 모델에 대해 claude를 실행하기 전에 둘 다 해주세요.

임시 해결책

아래의 Invoke 선호 설정과 베타 헤더 플래그는 임시적이에요. LiteLLM은 이미 게이트웨이 안에서 Bedrock 위에 많은 Anthropic API 기능을 재구현하고 있고, Converse 경로에서 그 범위를 꾸준히 확장하고 있어요. 곧 이런 해결책이 필요 없게 될 거예요.

1. Bedrock Invoke 선호

위 config에서 Bedrock 모델은 bedrock/invoke/ 접두사를 사용하는데, 현재 Claude Code 트래픽에 더 매끄러운 경로예요. Converse를 시도하고 싶다면 접두사를 bedrock/invoke/에서 bedrock/converse/로 바꾸고 필요한 기능에 대해 매트릭스를 확인해요.

2. Claude Code의 실험적 베타 헤더 Bedrock에서 비활성화

Claude Code는 매 요청마다 Anthropic 실험적 베타 헤더(예: anthropic-beta: prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20)를 붙여요. 이 헤더는 Anthropic 퍼스트파티 API에서는 잘 동작하지만, Bedrock은 현재 모두를 받아들이지 않아 400 invalid beta flag 오류를 반환할 수 있어요. CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 환경 변수를 1로 설정해 그 헤더를 제거해요.

설정을 권장하는 곳은 글로벌 Claude Code 사용자 설정 파일이에요.

~/.claude/settings.json

(macOS/Linux에서는 /Users//.claude/settings.json, Windows에서는 C:\Users\\.claude\settings.json. CLI, VS Code 확장, JetBrains 플러그인 등 모든 Claude Code 클라이언트가 이 파일을 읽어요.)

편집 방법:

  • 원하는 편집기로 ~/.claude/settings.json을 열어요. 없으면 만들어요.
# macOS / Linux - open with your default editor${EDITOR:-nano} ~/.claude/settings.json# Or with VS Codecode ~/.claude/settings.json
  • (기존에 있으면 병합해서) env 블록을 추가해요.

~/.claude/settings.json

{  "env": {    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"  }}
  • 새 설정이 적용되도록 Claude Code를 완전히 종료하고 다시 열어요. IDE 플러그인(VS Code, JetBrains)은 IDE를 재시작해요.

대안: 프로젝트 스코프 또는 셸 스코프

단일 프로젝트에서만 베타 헤더를 비활성화하려면 프로젝트 루트의 .claude/settings.json(커밋됨) 또는 .claude/settings.local.json(gitignore됨, 개인용)에 같은 env 블록을 넣어요.

CLI에는 셸 수준 export도 동작하지만(claude 실행 전에 export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1), IDE 플러그인에서는 동작하지 않아요.

더 알아보기 (Learn more)