Claude Code의 에이전트 코딩 세션은 파일 읽기·코드 작성·테스트 반복으로 단일 세션에 수십~수백 달러의 토큰을 소비할 수 있다. 여기에 레이트 리밋이나 외부 API 의존성이 더해지면 긴 작업 흐름이 중간에 끊길 위험도 있다. 2026년 현재 로컬 모델은 코드 완성·리팩터링·디버깅·코드베이스 설명 같은 일상적인 Claude Code 작업 대부분을 충분히 커버한다.

이 튜토리얼은 Ollama, LM Studio, llama.cpp 세 가지 로컬 추론 백엔드를 Claude Code에 연결하는 방법을 다룬다.

작동 원리

Claude Code는 내부적으로 Anthropic Messages API 형식으로 요청을 보낸다. ANTHROPIC_BASE_URL 환경변수를 설정하면 해당 요청이 Anthropic 서버 대신 지정한 로컬 서버로 향한다.

2026년 1월 Ollama가 Anthropic Messages API를 네이티브 지원하면서 번역 프록시 없이 이 연동이 가능해졌다. LM Studio는 v0.4.1부터, llama.cpp는 그 이전부터 동일 엔드포인트를 지원한다.

필수 환경변수

세 모델 티어 변수를 설정하지 않으면 Claude Code가 claude-sonnet-4-20250514 같은 모델명으로 로컬 서버에 요청을 보내고, 로컬 서버는 해당 모델이 없어 오류를 반환한다.

백엔드 1: Ollama

터미널만으로 모델 다운로드·서빙을 간단하게 처리하고 싶을 때 가장 적합한 선택이다.

요구 사항: macOS·Linux·Windows(WSL2 권장), RAM 16GB 이상, Ollama v0.14.0 이상

설치 및 모델 다운로드

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# 버전 확인 (0.14.0 이상 필요)
ollama version

# 서버 동작 확인 (기본 포트: 11434)
curl http://localhost:11434

# 코딩용 모델 다운로드 (GLM-4.7-Flash: 128K 컨텍스트, Apache 2.0)
ollama pull glm-4.7-flash:latest

Claude Code 연결

방법 1: 현재 터미널 세션에만 적용

export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_API_KEY="ollama"
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-4.7-flash:latest"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7-flash:latest"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-4.7-flash:latest"
claude

**방법 2: ~/.claude/settings.json에 영구 설정**

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",
    "ANTHROPIC_API_KEY": "ollama",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7-flash:latest",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7-flash:latest",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7-flash:latest"
  }
}

백엔드 2: LM Studio

GUI로 모델을 검색·관리하고 싶거나 서버 설정을 시각적으로 다루고 싶을 때 적합하다.

요구 사항: macOS·Windows·Linux, VRAM 6GB 이상 권장

설치 및 서버 시작

# 헤드리스 서버용 CLI 설치
curl -fsSL https://releases.lmstudio.ai/cli/install.sh | bash

# 또는 https://lmstudio.ai 에서 데스크탑 앱 다운로드

GUI 사용 시:

1. LM Studio 실행 후 모델 검색 (예: “qwen coder”, “devstral”)
2. 모델 다운로드
3. 왼쪽 사이드바의 <> Local Server 탭 선택
4. 컨텍스트 크기 설정 (최소 25,000 토큰 권장)
5. Start Server 클릭
6. 화면에 표시된 모델 식별자를 정확히 복사

Claude Code 연결

export ANTHROPIC_BASE_URL="http://localhost:1234"
export ANTHROPIC_API_KEY="local"
export ANTHROPIC_AUTH_TOKEN="local"
# LM Studio에 표시된 모델 식별자를 그대로 사용
export ANTHROPIC_DEFAULT_SONNET_MODEL="<모델-식별자>"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="<모델-식별자>"
export ANTHROPIC_DEFAULT_OPUS_MODEL="<모델-식별자>"
claude

모델 식별자가 정확하지 않으면 요청이 거부된다. LM Studio 서버 탭에서 표시된 문자열을 그대로 복사해야 한다.

백엔드 3: llama.cpp

추론 파라미터(양자화 방식, KV 캐시, 배치 크기, 스레드 수)를 세밀하게 제어하거나 오버헤드를 최소화하려는 경우에 적합하다.

요구 사항: GGUF 형식 모델 파일, CUDA GPU(선택), CMake + C++ 컴파일러(소스 빌드 시)

설치

# macOS
brew install llama.cpp

# Linux (CUDA 지원)
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Linux CPU 전용
cmake -B build
cmake --build build --config Release

모델 다운로드 및 서버 실행

# Hugging Face CLI 설치
pip install huggingface-hub

# GGUF 모델 다운로드 (예: GLM-4.7-Flash Q4_K_XL)
huggingface-cli download unsloth/GLM-4.7-Flash-GGUF \
  --include "GLM-4.7-Flash-Q4_K_XL.gguf" \
  --local-dir ./models

# llama-server 실행 (GPU 사용)
./build/bin/llama-server \
  -m ./models/GLM-4.7-Flash-Q4_K_XL.gguf \
  --port 8080 \
  -ngl 99          # GPU 레이어 수

Claude Code 연결

export ANTHROPIC_BASE_URL="http://localhost:8080"
export ANTHROPIC_API_KEY="local"
export ANTHROPIC_AUTH_TOKEN="local"
export ANTHROPIC_DEFAULT_SONNET_MODEL="local-model"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="local-model"
export ANTHROPIC_DEFAULT_OPUS_MODEL="local-model"
claude

백엔드 선택 가이드

참고 자료

• Pairing Claude Code with Local Models — KDnuggets (2026-06-14)