Claude Code에서 OpenAI 호환 형식 API를 사용하여 모든 기능을 활용하는 방법

문제 배경

Claude Code는 기본적으로 Anthropic API 형식(/v1/messages 엔드포인트)만 지원하지만, 많은 API 제공업체는 OpenAI 호환 형식(/v1/chat/completions 엔드포인트)만 제공합니다. 이로 인해 사용자는 Claude Code에서 이러한 제공업체의 서비스를 사용할 수 없습니다.

API 형식 비교

해결책: LiteLLM 프록시

LiteLLM은 통합된 LLM 프록시 라이브러리로 다음 기능을 제공합니다:

• Anthropic 형식의 요청 수신
• 자동으로 OpenAI 형식으로 변환하여 상위 API로 전송
• OpenAI 형식의 응답을 다시 Anthropic 형식으로 변환

작동 원리

Claude Code (Anthropic 형식)
    ↓
localhost:4000
    ↓
LiteLLM 프록시 (형식 변환)
    ↓
상위 API (OpenAI 형식)

상세 단계

1. LiteLLM 설치

pipx를 사용하여 설치합니다(시스템 Python 패키지 충돌을 방지하기 위해 권장):

# pipx 설치(없는 경우)
sudo apt install pipx

# LiteLLM 설치(proxy 의존성 포함)
pipx install litellm[proxy]

2. 설정 파일 생성

설정 파일 경로: ~/.config/litellm/config.yaml

model_list:
  # 사용자 정의 모델 이름 → 실제 OpenAI 모델
  - model_name: gpt-5.4
    litellm_params:
      model: openai/gpt-5.4
      api_base: https://your-provider.com/v1
      api_key: your-api-key

  - model_name: gpt-5.4-mini
    litellm_params:
      model: openai/gpt-5.4-mini
      api_base: https://your-provider.com/v1
      api_key: your-api-key

  # Claude 모델 이름 매핑(선택 사항, 식별 용이)
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: openai/gpt-5.4-mini
      api_base: https://your-provider.com/v1
      api_key: your-api-key

  - model_name: claude-opus-4-6
    litellm_params:
      model: openai/gpt-5.4
      api_base: https://your-provider.com/v1
      api_key: your-api-key

general_settings:
  master_key: your-api-key  # 프록시 서비스 인증 키

주요 설정 설명:

• model_name: Claude Code 요청 시 사용할 모델 이름(임의의 이름 가능)
• litellm_params.model: 상위로 실제로 전송할 모델, 형식은 openai/모델명
• api_base: 상위 OpenAI 호환 API 주소
• api_key: 상위 API 키
• master_key: LiteLLM 프록시 인증 키(기존 API 키를 그대로 사용하여 설정 간소화 가능)

3. systemd 사용자 서비스 설정

서비스 파일 경로: ~/.config/systemd/user/litellm-proxy.service

[Unit]
Description=LiteLLM 프록시 - OpenAI to Anthropic API 변환기
After=network.target

[Service]
Type=simple
ExecStart=/home/당신의_사용자명/.local/bin/litellm --config /home/당신의_사용자명/.config/litellm/config.yaml --port 4000
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

서비스 활성화:

# 설정 재로드
systemctl --user daemon-reload

# 부팅 시 자동 시작 활성화
systemctl --user enable litellm-proxy.service

# 서비스 시작
systemctl --user start litellm-proxy.service

# 상태 확인
systemctl --user status litellm-proxy.service

~/.bashrc 파일에 다음을 추가합니다:

# 원본 설정 (직접 상위 API 사용, Anthropic 형식 미지원)
export xl_key="your-api-key"
export xl_url="https://your-provider.com/v1"

# 새 설정: LiteLLM 프록시를 통한 사용
alias claude-xl='ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_AUTH_TOKEN=$xl_key ANTHROPIC_MODEL=gpt-5.4 claude'

설정 요점:

• ANTHROPIC_BASE_URL: LiteLLM 프록시 주소인 http://localhost:4000으로 변경
• ANTHROPIC_AUTH_TOKEN: 기존 API 키 사용 (master_key와 동일)
• ANTHROPIC_MODEL: 설정 파일에서 정의한 model_name 사용

사용 방법

프록시 정상 작동 여부 테스트

curl -s http://localhost:4000/v1/messages \
  -H "x-api-key: your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.4", "max_tokens": 20, "messages": [{"role": "user", "content": "hi"}]}'

Claude Code 실행

claude-xl

서비스 관리 명령어

# 상태 확인
systemctl --user status litellm-proxy

# 서비스 재시작
systemctl --user restart litellm-proxy

# 서비스 중지
systemctl --user stop litellm-proxy

# 로그 확인
journalctl --user -u litellm-proxy -f

# 최근 오류 확인
journalctl --user -u litellm-proxy -n 50 --no-pager | grep -i error

사용 가능한 모델 확인

# 상위 API가 지원하는 모델 확인
curl -s "https://your-provider.com/v1/models" \
  -H "Authorization: Bearer your-api-key"

# LiteLLM에 설정된 모델 확인
curl -s http://localhost:4000/v1/models \
  -H "Authorization: Bearer your-api-key"

자주 발생하는 문제

1. 모델 이름 오류

오류: Invalid model name passed in model=xxx

원인: 요청한 모델 이름이 LiteLLM 설정의 model_list에 정의되어 있지 않음.

해결 방법: config.yaml 파일에 해당 모델 매핑을 추가합니다:

- model_name: xxx
  litellm_params:
    model: openai/실제모델이름
    api_base: ...
    api_key: ...

2. 의존성 누락

오류: ModuleNotFoundError: No module named 'websockets'

해결 방법: 전체 의존성을 설치합니다:

pipx install litellm[proxy] --force

3. 상위 API 사용 불가

오류: Upstream service temporarily unavailable

이는 상위 API 제공업체의 문제이며, LiteLLM 설정 문제와 무관합니다. 복구될 때까지 기다리면 됩니다.

4. 서비스 시작 실패

로그 확인:

journalctl --user -u litellm-proxy -n 50 --no-pager

흔한 원인:

• 설정 파일 경로 오류
• pipx 설치 경로 오류 (ExecStart 경로 확인)
• 설정 파일 YAML 형식 오류

요약

LiteLLM 프록시를 통해 Claude Code는 모든 OpenAI 호환 형식의 API를 사용할 수 있습니다:

1. 설치: pipx install litellm[proxy]
2. 설정: ~/.config/litellm/config.yaml 생성 및 모델 매핑 정의
3. 서비스: systemd 사용자 서비스 설정하여 부팅 시 자동 시작
4. 사용: .bashrc alias 수정 시 URL만 변경하고 토큰 형식은 그대로 유지

이렇게 하면 Claude Code의 모든 기능이 활성화됩니다:

• 도움말 명령어
• 다중 대화 컨텍스트
• 도구 호출(Tool Use)
• 스트리밍 응답
• MCP 서버 통합

문서 작성일: 2026-03-29