Docker Model Runner와 Claude Code 사용하기

Source: Dev.to

번역을 진행하려면 번역하고자 하는 본문 텍스트를 제공해 주세요.
코드 블록, URL 및 마크다운 형식은 그대로 유지하면서 내용만 한국어로 번역해 드리겠습니다.

사전 요구 사항

• Docker Desktop 또는 Docker Engine이 설치되어 있어야 합니다.
• Docker Model Runner가 활성화되어 있어야 합니다.
• Claude Code가 설치되어 사용 준비가 되어 있어야 합니다.

Model Runner 활성화 (Docker Desktop)

1. Settings → AI를 엽니다.
2. TCP access for Model Runner를 켭니다.

Model Runner 활성화 (CLI)

docker desktop enable model-runner --tcp 12434

시작하기

1️⃣ 로컬 모델 선택 및 가져오기

하드웨어에 맞는 모델을 고르세요. 여기서는 ai/phi4:14B-Q4_K_M을 사용하지만, Docker Hub AI 카탈로그에서 제공되는 모든 모델이 작동합니다.

docker model pull ai/phi4:14B-Q4_K_M

모델 크기와 네트워크 속도에 따라 다운로드 시간이 달라집니다.

2️⃣ 연결 확인

Model Runner의 상태를 확인하고, 가져온 모델 목록을 확인합니다:

docker model status
docker model ls

3️⃣ API 엔드포인트 테스트

/v1/messages에 요청을 보내 로컬 엔드포인트가 정상적으로 응답하는지 확인합니다:

curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/phi4:14B-Q4_K_M",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello!"}]
  }' | jq .

아래와 같은 JSON 응답이 반환되어야 합니다:

4️⃣ Claude Code를 로컬 엔드포인트에 연결하기

Claude Code가 Anthropic 클라우드 대신 Docker Model Runner를 사용하도록 설정합니다:

ANTHROPIC_BASE_URL=http://localhost:12434 claude --model ai/devstral-small-2

Claude Code가 로컬 모델과 통신하는 모습을 확인할 수 있습니다:

5️⃣ 설정을 영구화하기

ANTHROPIC_BASE_URL 변수는 현재 쉘 세션에서만 유효합니다. 쉘 시작 파일(~/.zshrc, ~/.bashrc 등)에 추가하세요:

export ANTHROPIC_BASE_URL=http://localhost:12434

파일을 저장한 뒤 터미널을 재시작하거나 source ~/.zshrc / source ~/.bashrc 를 실행합니다. 이제부터 모델을 지정하면 Claude Code가 자동으로 로컬 엔드포인트를 사용합니다.

6️⃣ 로컬 모델로 Claude Code 실행하기

이제 로컬에 호스팅된 모델과 함께 Claude Code를 사용할 준비가 되었습니다:

claude --model ai/phi4:14B-Q4_K_M

Claude Code는 요청을 Docker Model Runner에 보내며, 데이터는 로컬에 남고 토큰 비용도 발생하지 않습니다.

6️⃣ 요청 흐름 보기

저처럼 약간은 괴짜라면, Claude Code가 로컬 모델에 보내는 모든 요청을 실시간으로 확인할 수 있습니다:

docker model requests --model ai/phi4:14B-Q4_K_M

다시 한 번, jq를 사용해 출력 포맷을 깔끔하게 정리했습니다.

Source: …

7. 다음은?

대부분의 모델에서 기본 컨텍스트 크기는 작은 작업에 충분하지만, Claude Code는 많은 파일을 읽습니다. 큰 프로젝트 작업을 할 때는 더 넓은 여유와 큰 컨텍스트가 필요합니다.

예를 들어, gpt-oss를 32 k 컨텍스트 윈도우로 패키징하려면:

docker model pull ai/gpt-oss
docker model package --from ai/gpt-oss --context-size 32000 gpt-oss:32k

그런 다음 새로운 변형으로 Claude Code를 실행합니다:

claude --model gpt-oss:32k

이게 핵심입니다: 다양한 모델과 컨텍스트 크기를 시도하고 실험하면서 작업에 가장 적합한 모델을 찾으세요.

---

이것으로 끝입니다! 이제 Docker Model Runner를 사용해 Claude Code를 완전히 로컬에서 실행할 수 있습니다.

한 번 시도해 보고 어떤 모델이 가장 잘 맞는지 알려 주세요.

항상 읽어 주셔서 감사합니다. 저는 Twitter에서 팁을 정기적으로 공유하고 있으니, 언제든지 연결해 주세요.