ClaudeCode 로컬 모델 사용법

요즘 내 개발작업의 90%를 ClaudeCode가 하고 정말 다양한 걸 시도해볼 수가 있어서 새벽에도 계속 작업을 하다 보니 Hourly limit은 안 걸리는데 Weekly Limit이 거의 간당간당해서 매주 살 떨린다.
그래서 간단한 서브 작업들은 로컬 LLM을 이용해 보고자 가이드를 작성하였다.

오늘은 로컬에 Qwen3 Coder Next 모델을 vLLM을 이용하여 서빙한 뒤 Claude Code에 연결해서 사용해 볼 것이다.

ollama 등은 claude code에서 바로 사용할 수 있게 세팅해 주는 옵션 등이 있는데 vLLM은 뭐 따로 할 건 없고, 그냥 claude code를 실행할 때 몇 가지 설정만 수동으로 바꿔주면 된다.

Qwen3 Coder Next

• MoE(Mixture of Experts) 구조로 총 80B 파라미터 중 활성 파라미터는 3B — 10~20배 큰 모델급 성능을 낸다고 한다
• 512개 전문가 중 10개만 활성화하는 구조 (Gated Attention + Gated DeltaNet + MoE 하이브리드)
• 최대 262K 토큰 컨텍스트 지원
• Non-thinking 모드만 지원 (thinking 블록 생성 안 함)
• 도구 호출(tool calling) 특화 설계, Apache 2.0 라이선스

에이전트 용도로 만든 모델답게, 장시간 추론이나 복잡한 도구 호출, 실행 오류 복구 같은 agentic 작업에 초점을 맞췄다.

 

 

게다가 Unsloth에서 다양한 크기의 양자화버전을 만들어줬느데, 아래에서 보다시피 양자화를 했음에도 성능이 매우 좋은 것을 확인할 수 있다.

Qwen/Qwen3-Coder-Next가 원래 150GB 정도의 vram을 요구하는데, 아래 차트를 보면 3비트 양자화의 경우 기존대비 약 100GB 정도의 Vram을 덜 쓰면서 유사한 성능을 낼 수 있다고 한다;;;;

unsloth는 아래버전들에 대한 gguf 양자화 버전이랑 unsloth/Qwen3-Coder-Next-FP8-Dynamic이라는 버전도 출시했으니 다양하게 직접 사용해 보면 좋을 것 같다.

 

Qwen3-Coder - a unsloth Collection

 

모델에 대한 설명은 여기까지 하고 이제 실제로 ClaudeCode에 연결을 해보자

---

vLLM 서빙

우선 당연하게도 Ollama 혹은 vLLM을 이용하여 로컬에 모델을 띄워놔야 한다.

Requirements

• GPU: FP8 양자화 기준 약 46GB VRAM 필요 (Qwen3-Coder-Next 기준)
• vllm >= 0.15.0 (Qwen3-Coder-Next 지원 버전)
• Python 환경

Installation

uv venv
source .venv/bin/activate
uv pip install -U vllm --torch-backend auto

vLLM 서버 시작

나는 단일 GPU 환경이라 작은 모델 기준으로 설명하겠지만, 기본 구조는 동일하다.

vllm serve Qwen/Qwen3-Coder-Next \
  --port 8000 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder

여기서 중요한 옵션이 두 개다.

• --enable-auto-tool-choice: 도구 호출 자동 감지 활성화
• --tool-call-parser qwen3_coder: Qwen3 Coder 전용 파서 사용

서버가 뜨면 http://localhost:8000으로 OpenAI 호환 API가 열린다.

---

Claude Code 연결

서버가 떴으면 이제 Claude Code가 Anthropic 대신 로컬 서버를 바라보도록 설정해야 한다. 방법은 단순하다.

환경변수 설정

export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_API_KEY="sk-no-key-required"

ANTHROPIC_API_KEY는 인증용인데, 로컬 서버니까 뭘 넣어도 상관없다. 그냥 빈 값이 아닌 아무 문자열이면 된다.

영구적으로 적용하려면 ~/.zshrc 또는 ~/.bashrc에 추가하면 된다.

# ~/.zshrc
export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_API_KEY="sk-no-key-required"

모델 지정해서 실행

claude --model Qwen/Qwen3-Coder-Next

모델 이름은 vLLM에 서빙한 모델 ID와 일치해야 한다.

연결 확인

설정이 제대로 됐는지 간단하게 테스트해 볼 수 있다.

curl http://localhost:8000/v1/models

서빙 중인 모델 목록이 나오면 서버는 정상이다. 이후 claude 커맨드를 실행했을 때 응답이 오면 연결 성공이다.

혹시나 위 방법으로 적용했는데도, 계속 ClaudeCode에서 연결하라는 창만 뜬다면 아래 방법을 시도해 보면 된다. 차이점은 모델 기본값들을 방금 서빙한 모델들로 전부 설정해 주는 것이다.
(나는 ClaudeCode 구독을 안 한 상태에서 시도해서 이 방법으로 하니 성공했다)

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

 

---

실제 사용 경험

솔직히 처음에는 "제대로 될까?" 반신반의했다. Claude Code는 tool calling을 정말 많이 쓰는 도구인데, 오픈소스 모델이 이걸 얼마나 잘 따라올지 확신이 없었다.

결론부터 말하면, 생각보다 잘 된다. 파일 편집, 터미널 명령 실행, 코드 검색 같은 기본적인 작업은 무리 없이 처리한다.
Anthropic Claude와 비교했을 때 복잡한 추론이나 긴 컨텍스트 처리에서는 차이가 느껴지긴 한다. 하지만 일상적인 코딩 작업, 예를 들어 함수 수정하거나 버그 찾거나 리팩토링하는 수준에서는 충분히 쓸 만하다.

---

References

• vLLM - Claude Code Integration
• Unsloth - Qwen3-Coder-Next
• Unsloth - Claude Code with Local Models
• vLLM Recipes - Qwen3-Coder-480B
• Qwen3-Coder-Next - Hugging Face
• Qwen3-Coder GitHub