Claude Code

Claude Code (CLI) 연결 (Connect Claude Code to LiteLLM)

Claude Code는 Anthropic Messages API와 통신해요. LiteLLM은 그 형식을 /v1/messages에서 서빙하므로, 두 환경 변수가 Claude Code를 게이트웨이로 향하게 하고, 콘피그의 어떤 모델에서나 Anthropic 모델이 아니어도 동작하게 돼요.

출처: 문서

본문

빠른 참조 (Quick reference)

설정	값
ANTHROPIC_BASE_URL	`<LITELLM_PROXY_BASE_URL>` (예: http://localhost:4000)
ANTHROPIC_AUTH_TOKEN	LiteLLM 가상 키
ANTHROPIC_MODEL	콘피그의 model_name
MCP 엔드포인트	`<LITELLM_PROXY_BASE_URL>/<server_name>/mcp`
MCP auth 헤더	`x-litellm-api-key: *** <virtual key>`

LLM 설정 (LLM setup)

1. Claude Code를 게이트웨이로 향하게 하기

base URL, 가상 키, 모델을 export한 다음 Claude Code를 시작하세요:

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-1234"
export ANTHROPIC_MODEL="claude-sonnet-5"
claude

Claude Code는 모든 요청을 LiteLLM의 /v1/messages 엔드포인트로 가상 키를 bearer 토큰으로 해서 보내요. 영구적으로 만들려면 export를 셸 프로파일(~/.zshrc, ~/.bashrc) 또는 Claude Code의 settings.json env 블록에 추가하세요. 셸에 ANTHROPIC_API_KEY도 설정돼 있다면, 이 세션에서는 이를 해제해 Claude Code가 가상 키 대신 그것을 보내지 않게 하세요.

2. 모델 선택하기

Claude Code는 선택된 모델 id를 그대로 보내므로, 그 id가 게이트웨이에 model_name으로 존재해야 해요. ANTHROPIC_MODEL은 기본값을 사용자 이름 중 하나로 고정해요. 세션 안의 /model 선택기는 여전히 Anthropic 자체 id(예: claude-haiku-4-5-20251001)를 나열하므로, 콘피그가 그 정확한 이름도 정의하지 않는 한 거기서 고르면 Invalid model name passed in으로 실패해요. 그 이름들을 model_list에 추가하거나, ANTHROPIC_MODEL로 계속 모델을 전환하세요. non-Anthropic 모델로 Claude Code 라우팅에서 Sonnet, Opus, Haiku 티어를 어떤 공급자에든 매핑하는 것을 다뤄요.

3. 검증 (Verify)

프롬프트를 보내세요. 여기서 Claude Code 2.1이 model_list의 모델로 설정된 ANTHROPIC_MODEL과 함께 로컬 게이트웨이를 통해 응답하고 있어요:

그런 다음 Admin UI의 Logs 또는 Usage에서 트래픽이 가상 키와 선택한 모델에 귀속되어 있는지 확인하세요.

MCP 설정 (MCP setup)

claude mcp add로 LiteLLM MCP 게이트웨이 도구를 Claude Code 안에서 노출하세요. URL은 <LITELLM_PROXY_BASE_URL>/<server_name>/mcp이고, <server_name>은 게이트웨이 콘피그의 mcp_servers: 아래 키와 일치하며, 가상 키는 x-litellm-api-key 헤더에 들어가요:

claude mcp add --transport http litellm-tools \
  http://localhost:4000/my_mcp_server/mcp \
  --header "x-litellm-api-key: *** sk-1234"

부분	의미
litellm-tools	Claude Code 안의 이 서버 이름. 아무거나 선택
http://localhost:4000/my_mcp_server/mcp	`<PROXY_URL>/<server_name>/mcp`. my_mcp_server는 게이트웨이의 `mcp_servers:` 아래 키와 일치해야 함
--header "x-litellm-api-key: *** sk-1234"	게이트웨이에 인증하는 가상 키

키에 my_mcp_server 액세스가 필요해요 (overview 참고). 그렇지 않으면 게이트웨이가 The key is not allowed to access the requested MCP servers로 연결을 거부해요. Claude Code를 시작하고 /mcp를 실행하세요. 서버가 연결됨으로 표시되고, 서버 이름이 접두사로 붙은 도구(my_mcp_server-read_wiki_structure)가 나열돼요.

업스트림 OAuth 뒤에 있는 서버(예: 호스팅된 GitHub 또는 Atlassian MCP)의 경우 LiteLLM 키를 x-litellm-api-key에 유지하고 LiteLLM이 OAuth 플로우를 실행하게 하세요. MCP OAuth 참고.

다음 단계 (Next steps)

예산, 프롬프트 캐싱, 폴백으로 Claude Code 비용을 줄이고, 자체 Anthropic 키를 가져오거나, non-Anthropic 모델로 Claude Code 라우팅하거나, Claude Code 호환성 매트릭스를 확인하세요.