IDE 및 도구 통합

Docker Model Runner는 인기 있는 AI 코딩 어시스턴트와 개발 도구의 로컬 백엔드로 사용할 수 있어요. 이 가이드는 일반적인 도구가 DMR에서 실행되는 모델을 사용하도록 구성하는 방법을 보여드려요.

출처: 문서

본문

사전 요구 사항

도구를 구성하기 전에:

Docker Desktop 또는 Docker Engine에서 Docker Model Runner를 활성화합니다.
TCP 호스트 접근을 활성화합니다:
- Docker Desktop: Settings > AI에서 호스트 측 TCP 지원을 활성화하거나 실행하세요: $ docker desktop enable model-runner --tcp 12434
- Docker Engine: TCP는 포트 12434에서 기본적으로 활성화돼요.
모델을 풀합니다: $ docker model pull ai/qwen2.5-coder

팁: 많은 모델(예: gpt-oss)의 기본 컨텍스트 크기는 4,096 토큰으로 코딩 작업에는 제한적이에요. 더 큰 컨텍스트 창으로 다시 패키징할 수 있어요:
$ docker model pull gpt-oss
$ docker model package --from ai/gpt-oss --context-size 32000 gpt-oss:32k
또는 ai/glm-4.7-flash, ai/qwen2.5-coder, ai/devstral-small-2 같은 모델은 기본 128K 컨텍스트로 제공되어 다시 패키징할 필요가 없어요.

Cline(VS Code)

Cline은 VS Code용 AI 코딩 어시스턴트예요.

구성

VS Code를 열고 Cline 확장 설정으로 이동합니다.
API 제공자로 OpenAI Compatible을 선택합니다.
다음 설정을 구성합니다:

설정	값
Base URL	`http://localhost:12434/engines/v1`
API Key	`not-needed`(또는 아무 플레이스홀더 값)
Model ID	`ai/qwen2.5-coder`(또는 원하는 모델)

중요: Base URL 끝에 /engines/v1이 포함되어야 해요. 후행 슬래시는 넣지 마세요.

Cline 문제 해결

Cline이 연결에 실패하면:

DMR이 실행 중인지 확인: $ docker model status
엔드포인트를 직접 테스트: $ curl http://localhost:12434/engines/v1/models
웹 기반 버전을 실행 중이라면 CORS가 구성되어 있는지 확인: Docker Desktop Settings > AI에서 CORS Allowed Origins에 오리진 추가

Continue(VS Code / JetBrains)

Continue는 VS Code와 JetBrains IDE에서 동작하는 오픈소스 AI 코드 어시스턴트예요.

구성

Continue 구성 파일(~/.continue/config.json)을 편집해요:

{
  "models": [
    {
      "title": "Docker Model Runner",
      "provider": "openai",
      "model": "ai/qwen2.5-coder",
      "apiBase": "http://localhost:12434/engines/v1",
      "apiKey": "not-needed"
    }
  ]
}

Ollama 제공자 사용

Continue는 DMR과 함께 동작하는 Ollama 제공자도 지원해요:

{
  "models": [
    {
      "title": "Docker Model Runner (Ollama)",
      "provider": "ollama",
      "model": "ai/qwen2.5-coder",
      "apiBase": "http://localhost:12434"
    }
  ]
}

Cursor

Cursor는 AI 기반 코드 편집기예요.

구성

Cursor 설정(Cmd/Ctrl + ,)을 엽니다.
Models > OpenAI API Key로 이동합니다.
다음과 같이 구성합니다:

설정	값
OpenAI API Key	`not-needed`
Override OpenAI Base URL	`http://localhost:12434/engines/v1`

모델 드롭다운에 모델 이름을 입력합니다: ai/qwen2.5-coder

참고: 일부 Cursor 기능은 특정 기능(예: 함수 호출)이 있는 모델을 요구할 수 있어요. ai/qwen2.5-coder나 ai/llama3.2 같은 유능한 모델을 사용해 최상의 결과를 얻으세요.

Zed

Zed는 AI 기능을 갖춘 고성능 코드 편집기예요.

구성

Zed 설정(~/.config/zed/settings.json)을 편집해요:

{
  "language_models": {
    "openai": {
      "api_url": "http://localhost:12434/engines/v1",
      "available_models": [
        {
          "name": "ai/qwen2.5-coder",
          "display_name": "Qwen 2.5 Coder (DMR)",
          "max_tokens": 8192
        }
      ]
    }
  }
}

Open WebUI

Open WebUI는 로컬 모델을 위한 ChatGPT 같은 인터페이스를 제공해요. 자세한 설정 안내는 Open WebUI 통합 문서를 참고해 주세요.

Aider

Aider는 터미널용 AI 페어 프로그래밍 도구예요.

구성

환경 변수를 설정하거나 명령줄 플래그를 사용해요:

export OPENAI_API_BASE=http://localhost:12434/engines/v1
export OPENAI_API_KEY=not-needed
aider --model openai/ai/qwen2.5-coder

또는 단일 명령으로:

$ aider --openai-api-base http://localhost:12434/engines/v1 \
  --openai-api-key not-needed \
  --model openai/ai/qwen2.5-coder

LangChain

Python

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="not-needed",
    model="ai/qwen2.5-coder"
)
response = llm.invoke("Write a hello world function in Python")
print(response.content)

JavaScript/TypeScript

import { ChatOpenAI } from "@langchain/openai";
const model = new ChatOpenAI({
  configuration: {
    baseURL: "http://localhost:12434/engines/v1",
  },
  apiKey: "not-needed",
  modelName: "ai/qwen2.5-coder",
});
const response = await model.invoke("Write a hello world function");
console.log(response.content);

LlamaIndex

from llama_index.llms.openai_like import OpenAILike
llm = OpenAILike(
    api_base="http://localhost:12434/engines/v1",
    api_key="not-needed",
    model="ai/qwen2.5-coder"
)
response = llm.complete("Write a hello world function")
print(response.text)

OpenCode

OpenCode는 개발자 워크플로에 직접 통합되도록 설계된 오픈소스 코딩 어시스턴트예요. 여러 모델 제공자를 지원하고 그 사이를 쉽게 전환할 수 있게 해 주는 유연한 구성 시스템을 제공해요.

모델 설정, 구성, 문제 해결을 단계별로 안내하는 작업 중심 가이드는 Use OpenCode with Docker Model Runner 문서를 참고해 주세요.

구성

OpenCode를 설치합니다(문서 참고).
전역적으로 ~/.config/opencode/opencode.json에, 또는 프로젝트 루트의 opencode.json 파일로 프로젝트별로 OpenCode 구성에서 DMR을 참조합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "dmr": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Docker Model Runner",
      "options": {
        "baseURL": "http://localhost:12434/v1"
      },
      "models": {
        "ai/qwen2.5-coder": {
          "name": "ai/qwen2.5-coder"
        },
        "ai/llama3.2": {
          "name": "ai/llama3.2"
        }
      }
    }
  }
}

OpenCode에서 원하는 모델을 선택합니다.

이 Docker 블로그 게시물에서 더 자세한 내용을 찾을 수 있어요.

Claude Code

Claude Code는 에이전트 코딩을 위한 Anthropic의 명령줄 도구예요. 터미널에 살면서 코드베이스를 이해하고, 일상적인 작업을 실행하고, 복잡한 코드를 설명하고, 자연어 명령으로 Git 워크플로를 처리해요.

모델 설정, 구성, 요청 검사를 단계별로 안내하는 작업 중심 가이드는 Use Claude Code with Docker Model Runner 문서를 참고해 주세요. 로컬 모델로 격리된 Docker Sandbox에서 Claude Code를 실행하려면 Run Claude Code in a Docker Sandbox with Docker Model Runner 문서를 참고해 주세요.

구성

Claude Code를 설치합니다(문서 참고).
ANTHROPIC_BASE_URL 환경 변수를 사용해 Claude Code를 DMR로 지정합니다. Mac이나 Linux에서는, 예를 들어 gpt-oss:32k 모델을 사용하고 싶다면 이렇게 할 수 있어요:

ANTHROPIC_BASE_URL=http://localhost:12434 claude --model qwen2.5-coder

Windows(PowerShell)에서는 이렇게 할 수 있어요:

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

팁: 매번 변수를 설정하지 않으려면 셸 프로파일(~/.bashrc, ~/.zshrc 또는 동등한 파일)에 추가하세요:
export ANTHROPIC_BASE_URL=http://localhost:12434

이 Docker 블로그 게시물에서 더 자세한 내용을 찾을 수 있어요.

참고: 이 페이지의 다른 통합들은 OpenAI 호환 API를 사용하지만, DMR은 여기에서 사용되는 Anthropic 호환 API도 노출해요.

일반적인 문제

"Connection refused" 오류

Docker Model Runner가 활성화되고 실행 중인지 확인해요:

$ docker model status

TCP 접근이 활성화되어 있는지 확인해요:

$ curl http://localhost:12434/engines/v1/models

다른 서비스가 포트 12434를 사용하고 있는지 확인해요.

WSL에서 도구를 실행하고 localhost를 통해 호스트의 DMR에 연결하려면 바로 동작하지 않을 수 있어요. WSL을 미러 네트워킹으로 구성하면 이 문제를 해결할 수 있어요.

"Model not found" 오류

모델이 풀되었는지 확인해요:

$ docker model list

네임스페이스를 포함한 전체 모델 이름을 사용하세요(예: qwen2.5-coder가 아니라 ai/qwen2.5-coder).

느린 응답이나 타임아웃

첫 요청에서는 모델을 메모리에 로드해야 해요. 이후 요청은 더 빨라요.

더 작은 모델을 사용하거나 컨텍스트 크기를 조정하는 것을 고려해요:

$ docker model configure --context-size 4096 ai/qwen2.5-coder

사용 가능한 시스템 리소스(RAM, GPU 메모리)를 확인해요.

CORS 오류(웹 기반 도구)

브라우저 기반 도구를 사용한다면 CORS 허용 오리진에 오리진을 추가해요:

Docker Desktop: Settings > AI > CORS Allowed Origins
도구의 URL을 추가하세요(예: http://localhost:3000)

사용 사례별 권장 모델

사용 사례	권장 모델	참고
코드 완성	`ai/qwen3-coder`	큰 컨텍스트 창으로 코딩 작업에 최적
에이전트 코딩	`ai/devstral-small-2`	Claude Code와 OpenCode 같은 도구에 좋음
일반 어시스턴트	`ai/llama3.2`	기능의 좋은 균형
작고 빠름	`ai/smollm2`	리소스 사용량이 낮음
임베딩	`ai/all-minilm`	RAG와 시맨틱 검색용

다음 단계

API 레퍼런스 — 전체 API 문서
구성 옵션 — 모델 동작 조정
Open WebUI 통합 — 웹 인터페이스 설정

IDE 및 도구 통합