Claude Code를 무료로? 로컬 LLM 서버에 직접 연결하는 방법

마지막 수정일 2026.06.14.

최근 코딩 에이전트 대장, 클로드 코드는 보통 Anthropic의 유료 모델을 쓴다. Opus라든가 Sonnet이라든가. 그런데 ANTHROPIC_BASE_URL 환경 변수를 한 줄 넣어주면, 로컬에 돌려둔 LLM 서버를 백엔드로 쓸 수 있다.

이 글에서는 클로드 코드를 로컬 LLM에 연결하는 방법을 다룬다. 클로드 코드와 로컬 LLM의 관계, 왜 클로드 코드를 쓰는 게 나은지, 그리고 단점은 무엇인지 함께 살펴보자.

클로드 코드와 로컬 LLM, 어떤 관계인가

먼저 기본 구조부터 짚고 넘어가자. 클로드 코드는 Anthropic의 Messages API (/v1/messages 엔드포인트)를 통해서만 LLM과 대화한다. 디폴트로는 Anthropic 서버가 이 일을 해주지만, 이 주소를 ANTHROPIC_BASE_URL로 바꿔서 내 서버로 돌릴 수 있는 게 핵심이다.

구체적으로 말하면 이렇다.

클로드 코드가 ANTHROPIC_BASE_URL/v1/messages로 POST 요청을 보낸다.
요청 본문은 Anthropic Messages 형식 — model, messages[](system, user, assistant role 포함), max_tokens 따위.
LLM 서버가 응답하면 클로드 코드가 결과를 화면에 보여준다.

Anthropic 서버가 아닌 vLLM이나 LM Studio 같은 로컬 서버로 방향을 바꿔주는 게 ANTHROPIC_BASE_URL의 유일한 일이다. Anthropic API 키나 구독과 전혀 관계없어진다. “Not logged in” 오류도 사라진다.

단, 여기서 주의할 점이 하나 있다. Anthropic Messages API를 직접 지원하는 서버(예: vLLM 0.23.0+)라면 이대로 쓰면 되지만, OpenAI 호환 API만 제공하는 서버라면 프록시가 필요하다. LiteLLM이나 Claude Code Router 같은 게 대표적이다. 프록시가 Anthropic 형식을 OpenAI 형식으로 바꿔준다.

로컬 LLM 서버 준비

클로드 코드가 쓸 LLM 서버를 준비해야 한다. 대표적인 옵션은 두 가지다.

LM Studio

로컬에서 쉽게 돌릴 수 있는 옵션이다. GUI가 제공돼 모델을 쉽게 찾을 수 있고, API 서버를 한 번 실행하면 Anthropic 호환 엔드포인트가 바로 준비된다.

로컬에 모델을 쉽게 다운로드
GUI 제공으로 설정이 간편
기본 포트 1234에서 Anthropic 호환 API 제공

LM Studio를 실행하면 localhost:1234에서 Anthropic 호환 API를 제공하므로, 클로드 코드 설정에서 ANTHROPIC_BASE_URL을 http://localhost:1234로 설정하면 된다.

vLLM

대용량 모델을 빠르게 서빙하려면 vLLM이 적합하다. 특히 system role를 공식적으로 지원하려면 vLLM 0.23.0 이상이 필요한데, 이 버전부터 role: "system"이 /v1/messages 엔드포인트에서 제대로 처리된다.

vLLM은 Docker로 쉽게 올릴 수 있다.

docker run -d --name vllm-server \
  -p 8000:8000 \
  --gpus all \
  vllm/vllm-openai:v0.23.0-ubuntu2404 \
  --model <your-model-name> \
  --max-model-len 262144

두 옵션 모두 localhost:8000 (vLLM 기준) 또는 localhost:1234 (LM Studio 기준)에서 Anthropic 호환 API를 제공한다. 아래서는 vLLM을 기준으로 설명하지만, LM Studio도 포트만 바꾸면 동일하게 작동한다.

왜 LLM API가 아니라 클로드 코드인가

단순히 curl로 LLM API를 호출하는 것과 클로드 코드를 쓰는 것은 완전히 다르다. 클로드 코드는 텍스트 생성기를 넘어 코딩 에이전트다.

구체적으로 어떤 도구를 쓰는지 나열해보자.

파일 읽기/쓰기: 소스 코드를 읽고, 수정하고, 새로운 파일을 만든다. 단순히 diff만 보여주는 게 아니라 실제로 파일에 쓴다.
터미널 명령 실행: 빌드, 테스트, 배포 명령을 직접 실행하고 결과를 확인한다. 터미널 출력을 보고 다음 행동을 결정한다.
코드베이스 검색: 프로젝트 전체에서 심볼을 찾고, import 그래프를 분석하고, 관련 파일을 탐색한다.
대화형 컨텍스트 관리: 수백 줄에 달하는 대화 이력을 유지하면서 맥락을 잃지 않고 작업을 이어간다.

단순 API 호출은 “질문 → 답장”의 일방향이지만, 클로드 코드는 이 도구들을 조합해서 자율적으로 문제를 해결한다. “이 코드 고쳐줘”라고 하면 모델이 직접 파일을 읽고, 수정하고, 테스트를 실행하고, 실패하면 다시 고친다. 사람이 매번 터미널을 열어서 명령을 치고 파일을 고칠 필요가 없다.

물론 이 모든 능력은 모델의 품질에 달려 있다. 로컬 LLM이 클로드(Sonnet/Opus)보다 현저히 뒤지기 때문에, 같은 작업을 해도 실패율이 더 높고 추론 단계에서 덜 정확하게 판단할 수 있다. 하지만 에이전트 구조 자체는 동일하게 유지된다.

클로드 코드의 단점과 로컬 대안

그렇다면 왜 모두 클로드 코드의 유료 모델을 쓰지 않을까. 몇 가지 현실적인 제약이 있다.

비용

클로드 코드는 Anthropic 모델을 구독하거나 토큰 단위로 과금한다.

플랜	가격	특징
Pro	$20/월	Claude Sonnet 접근. 주당 사용량 제한 있음
Max	$100/월	Claude Opus 접근. 더 높은 사용량 제한
API (페이유즈)	토큰 단위	입력 3~15$/M 토큰, 출력 15~75$/M 토큰

코딩 작업은 토큰을 많이 먹는다. 큰 코드베이스를 탐색하고 수정하는 데 수만~수십만 토큰이 쌓이기 쉽다. 특히 Max 플랜(Opus)은 토큰 비용이 높아 하루 몇 시간만 써도 부담이 될 수 있다.

속도 제한

모든 플랜에는 속도 제한이 있다. Pro는 주당 5시간, Max는 주당 15~25시간(플랜에 따라 다름)으로, 제한 시간이 초과하면 잠시 기다려야 한다.

네트워크 의존성

클로드 코드는 Anthropic 서버와 항상 연결되어 있어야 한다. 인터넷이 끊기면 사용할 수 없다. 오프라인 환경이나 폐쇄된 내부망에서는 아예 작동하지 않는다.

벤더 락인

Claude 전용 API를 쓰므로 다른 모델로 쉽게 갈아낄 수 없다. Gemini나 GPT로 바꾸려면 도구 자체가 달라지는 것이지, 단순히 API 키만 바꾸면 되는 일이 아니다.

이런 제약 때문에 로컬 LLM을 쓰는 이유가 명확해진다.

비용 제로 — GPU만 있으면 추가 비용 없음
오프라인 작동 — 인터넷 연결 불필요
데이터 프라이버시 — 코드와 문제가 외부로 나가지 않음
모델 유연성 — 원하는 모델을 언제든지 교체 가능

설정 파일 편집

~/.claude/settings.json에서 고쳐주면 된다.

{
  "model": "<your-model-name>",
  "effortLevel": "high",
  "theme": "dark",
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8000",
    "ANTHROPIC_API_KEY": "sk-dummy",
    "ANTHROPIC_AUTH_TOKEN": "sk-dummy",
  },
}

필드마다 어떤 일을 하는지 정리하면 이렇다.

설정 항목	값	용도
`model`	실제 모델명	클로드 코드가 API에 요청할 모델 식별자
`ANTHROPIC_BASE_URL`	`http://localhost:8000`	LLM 서버 주소. `/v1`은 붙이지 않음 — 클로드 코드가 내부적으로 `/v1/messages`를 붙여줌
`ANTHROPIC_API_KEY`	`sk-dummy`	로컬 LLM은 인증이 필요없으니 더미 키로 충분
`ANTHROPIC_AUTH_TOKEN`	`sk-dummy`	인증 토큰. 로컬 LLM은 인증이 필요없으니 더미 키로 충분

ANTHROPIC_BASE_URL 값에 /v1을 붙이면 안 된다. 클로드 코드가 내부적으로 이 URL에 /v1/messages, /v1/models 등을 자동으로 붙여주기 때문이다. /v1까지 같이 붙이면 결국 http://localhost:8000/v1/v1/messages가 돼 404가 뜬다.

실제 동작 확인

설정이 끝나면 클로드 코드를 실행한 뒤 로컬 모델이 정상적으로 선택되는지 확인하자.

간단하게는 claude -p "message"로 테스트하는 것도 가능하다. 이제 집접 잘 구동 되는지 확인해보자.

야호! 성공했다. 이제 (다소 멍청하지만) 로컬 LLM - 클로드 코드로 마구마구 코딩해보자.

주의사항

클로드 코드 버전

클로드 코드 2.1.154 이상부터 system role를 messages[]에 포함하기 시작한다. 구버전(2.1.153 이하)에서는 문제가 없었지만, 최신 버전은 Anthropic의 Messages API 형식을 더 Strict하게 따른다.

# 버전 확인
claude --version

# 필요시 업그레이드
claude update

Docker 환경

클로드 코드가 Docker 컨테이너 내부에서 돌아간다면 ANTHROPIC_BASE_URL이 컨테이너 내부에서 접근 가능한 주소여야 한다. localhost는 컨테이너 자신의 localhost지, 호스트의 localhost가 아니다. 이 경우 host.docker.internal이나 실제 호스트 IP를 사용해야 한다.

로컬 LLM을 클로드 코드와 연동하면 Anthropic API 비용 없이 코드 작성, 수정, 실행을 모두 할 수 있다. 핵심은 ANTHROPIC_BASE_URL에 LLM 서버 주소를 설정하는 것(포트 뒤 /v1은 붙이지 말 것), ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_API_KEY 더미 키를 함께 넣어서 “Not logged in”을 우회하는 것, 그리고 model 필드를 실제 모델명으로 유지하는 것이다.

문제가 생겼을 때는 ~/.claude/.credentials.json을 삭제한 뒤 claude를 다시 실행하면 fresh start할 수 있다.