Claude Code를 Docker Model Runner와 함께 사용하기

Claude Code를 Docker Model Runner와 함께 사용하기 (Use Claude Code with Docker Model Runner)

Anthropic 호환 API, 더 큰 컨텍스트 윈도우를 가진 gpt-oss 패키징, 요청 검사로 Claude Code를 Docker Model Runner에 연결하는 방법을 설명하는 가이드예요.

출처: 문서

본문

이 가이드는 Claude Code를 백엔드 모델 공급자로 Docker Model Runner와 함께 실행하는 방법을 보여줘요. 로컬 Anthropic 호환 API에 Claude Code를 연결하고, 코딩 모델을 실행하며, 더 긴 저장소 프롬프트를 위해 더 큰 컨텍스트 윈도우로 gpt-oss를 패키징하게 됩니다.

감사의 말 (Acknowledgment): Docker는 이 가이드에 기여해준 Pradumna Saraf에게 감사드려요.

이 가이드에서 다음을 배우게 됩니다:

코딩 모델을 pull하고 Docker Model Runner로 Claude Code 시작하기
엔드포인트 구성을 영구적으로 만들기
로컬 API 엔드포인트 검증 및 요청 검사
더 긴 프롬프트를 위해 더 큰 컨텍스트 윈도우로 gpt-oss 패키징하기

사전 요구사항 (Prerequisites)

시작하기 전에 다음이 있는지 확인하세요:

Docker Desktop을 사용한다면 Settings > AI에서 TCP 접근을 켜거나 다음을 실행하세요:

$ docker desktop enable model-runner --tcp 12434

1단계: 코딩 모델 pull하기 (Step 1: Pull a coding model)

Claude Code를 시작하기 전에 모델을 pull하세요:

$ docker model pull ai/devstral-small-2

큰 컨텍스트 윈도우를 가진 다른 코딩 중심 모델을 원한다면 ai/qwen3-coder를 사용할 수도 있어요.

2단계: Claude Code를 Docker Model Runner로 시작하기 (Step 2: Start Claude Code with Docker Model Runner)

Claude Code를 실행할 때 ANTHROPIC_BASE_URL을 로컬 Docker Model Runner 엔드포인트로 설정하세요.

macOS 또는 Linux:

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

Windows PowerShell:

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

이제 Claude Code는 Anthropic의 호스팅 API 대신 Docker Model Runner에 요청을 보내요.

3단계: 첫 실행 문제 해결 (Step 3: Troubleshoot your first launch)

Claude Code가 연결할 수 없다면 Docker Model Runner 상태를 확인하세요:

$ docker model status

Claude Code가 모델을 찾을 수 없다면 로컬 모델을 나열하세요:

$ docker model ls

모델이 없다면 먼저 pull하세요. 필요한 경우 ai/devstral-small-2 같은 정규화된 모델 이름을 사용하세요.

4단계: 엔드포인트 영구화하기 (Step 4: Make the endpoint persistent)

매번 환경 변수를 설정하지 않으려면 셸 프로필에 추가하세요:

~/.bashrc 또는 ~/.zshrc:

export ANTHROPIC_BASE_URL=http://localhost:12434

Windows PowerShell에서는 PowerShell 프로필에 추가하세요:

$PROFILE:

$env:ANTHROPIC_BASE_URL = "http://localhost:12434"

셸을 다시 로드한 후 모델 플래그만으로 Claude Code를 실행할 수 있어요:

$ claude --model ai/devstral-small-2

5단계: API 엔드포인트 검증하기 (Step 5: Verify the API endpoint)

Anthropic 호환 API가 도달 가능한지 확인하기 위해 테스트 요청을 보내세요:

$ curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/devstral-small-2",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "Say hello"}]
  }'

요청 형식에 대한 자세한 내용은 Anthropic-compatible API reference를 참조하세요.

6단계: Claude Code 요청 검사하기 (Step 6: Inspect Claude Code requests)

Claude Code가 Docker Model Runner에 보내는 요청을 검사하려면 다음을 실행하세요:

$ docker model requests --model ai/devstral-small-2 | jq .

이것은 프롬프트, 컨텍스트 사용량, 호환성 문제를 디버그하는 데 도움이 돼요.

7단계: 더 큰 컨텍스트 윈도우로 gpt-oss 패키징하기 (Step 7: Package gpt-oss with a larger context window)

ai/gpt-oss는 기본적으로 코딩 중심 모델보다 작은 컨텍스트 윈도우를 사용해요. 저장소 규모의 프롬프트에 사용하려면 더 큰 변형을 패키징하세요:

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

그런 다음 패키징된 모델로 Claude Code를 실행하세요:

$ ANTHROPIC_BASE_URL=http://localhost:12434 claude --model gpt-oss:32k

Claude Code를 Docker Model Runner와 함께 사용하기