Claude Code

Claude Code

Claude Code는 Anthropic의 공식 에이전틱 코딩 도구로, 터미널에서 동작합니다. 코드베이스를 이해하고 파일을 편집하며 명령을 실행해 더 효율적으로 코드를 작성할 수 있게 해 줍니다. Claude Code를 vLLM 서버에 연결하면 Anthropic API 대신 자신의 모델을 백엔드로 사용할 수 있습니다.

출처: 문서

본문

Claude Code는 Anthropic의 공식 에이전틱 코딩 도구로 터미널에서 동작합니다. 코드베이스를 이해하고 파일을 편집·명령을 실행하며 코드를 더 효율적으로 작성하게 도와줍니다.

Claude Code를 vLLM 서버에 연결하면 Anthropic API 대신 자신의 모델을 백엔드로 쓸 수 있습니다. 이는 다음에 유용합니다:

  • 완전히 로컬/비공개 코딩 지원 실행
  • 툴 호출 능력을 가진 오픈 가중치 모델 사용
  • 커스텀 모델로 테스트·개발

동작 방식 (How It Works)

vLLM은 Anthropic Messages API를 구현합니다. 이는 Claude Code가 Anthropic 서버와 통신할 때 사용하는 것과 같은 API입니다. ANTHROPIC_BASE_URL을 vLLM 서버로 설정하면 Claude Code가 요청을 Anthropic 대신 vLLM으로 보냅니다. vLLM은 이 요청을 로컬 모델에 맞게 변환하고 Claude Code가 기대하는 형식으로 응답을 반환합니다.

즉, 적절한 툴 호출을 지원하는 vLLM 서빙 모델은 Claude Code에서 Claude 모델의 drop-in 대체품으로 동작할 수 있습니다.

요구사항 (Requirements)

Claude Code는 강력한 툴 호출 능력을 가진 모델을 요구합니다. 모델은 OpenAI 호환 툴 호출 API를 지원해야 합니다. 모델에서 툴 호출을 활성화하는 방법은 Tool Calling을 참고하세요.

설치 (Installation)

먼저 공식 설치 가이드를 따라 Claude Code를 설치하세요.

vLLM 서버 시작 (Starting the vLLM Server)

툴 호출 가능 모델로 vLLM을 시작하세요 — openai/gpt-oss-120b를 쓰는 예시:

vllm serve openai/gpt-oss-120b --served-model-name my-model --enable-auto-tool-choice --tool-call-parser openai

다른 모델은 --enable-auto-tool-choice와 올바른 --tool-call-parser로 툴 호출을 명시적으로 활성화해야 합니다. 모델에 맞는 플래그는 Tool Calling 문서를 참고하세요.

Claude Code 구성 (Configuring Claude Code)

vLLM 서버를 가리키는 환경 변수로 Claude Code를 시작하세요:

ANTHROPIC_BASE_URL=http://localhost:8000 \
ANTHROPIC_API_KEY=dummy \
ANTHROPIC_AUTH_TOKEN=dummy \
ANTHROPIC_DEFAULT_OPUS_MODEL=my-model \
ANTHROPIC_DEFAULT_SONNET_MODEL=my-model \
ANTHROPIC_DEFAULT_HAIKU_MODEL=my-model \
claude

환경 변수:

변수 설명
ANTHROPIC_BASE_URL vLLM 서버를 가리킴 (기본 포트 8000)
ANTHROPIC_API_KEY vLLM은 기본적으로 인증을 요구하지 않으므로 아무 값이든 가능
ANTHROPIC_AUTH_TOKEN 필수. 아무 값이든 가능
ANTHROPIC_DEFAULT_OPUS_MODEL Opus 등급 요청용 모델 이름
ANTHROPIC_DEFAULT_SONNET_MODEL Sonnet 등급 요청용 모델 이름
ANTHROPIC_DEFAULT_HAIKU_MODEL Haiku 등급 요청용 모델 이름

팁

이 환경 변수들을 셸 프로파일(예: .bashrc, .zshrc), Claude Code 구성 파일(~/.claude/settings.json), 또는 래퍼 스크립트에 추가하면 편리합니다.

경고

최근 Claude Code가 시스템 프롬프트에 요청별 해시를 주입하기 시작했습니다. 이는 요청마다 프롬프트를 바꿔 prefix caching을 무력화하고 성능을 크게 떨어뜨릴 수 있습니다. vLLM > 0.17.1 버전에서는 자동으로 처리되지만, 더 오래된 버전에서는 ~/.claude/settings.json의 "env" 섹션에 "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"을 추가해야 합니다(Unsloth의 이 블로그 포스트 참고).

설정 테스트 (Testing the Setup)

Claude Code가 실행되면 간단한 프롬프트로 연결을 확인해 보세요.

모델이 올바르게 응답하면 설정이 작동하는 것입니다. 이제 vLLM 서빙 모델로 Claude Code를 코딩 작업에 사용할 수 있습니다.

문제 해결 (Troubleshooting)

연결 거부 (Connection refused): vLLM이 지정된 URL에서 실행 중이고 접근 가능한지 확인하세요. 포트가 일치하는지 확인하세요.

툴 호출이 작동하지 않음: 모델이 툴 호출을 지원하고 올바른 --tool-call-parser 플래그로 활성화했는지 확인하세요. Tool Calling 참고.

모델을 찾을 수 없음: --served-model-name이 환경 변수의 모델 이름과 일치하는지 확인하세요. Huggingface에서 직접 가져온 openai/gpt-oss-120b처럼 /가 있는 모델 이름은 사용할 수 없으니, Claude Code의 이런 제한에 주의하세요.

더 알아보기 (Learn more)