OpenCode를 Docker Model Runner와 함께 사용하기

OpenCode를 OpenAI 호환 엔드포인트로 Docker Model Runner에 연결하고, 코딩 모델을 선택하며, 더 큰 컨텍스트 윈도우로 gpt-oss 를 패키징해볼게요.

출처: 문서

본문

이 가이드는 OpenCode를 Docker Model Runner에 연결해 OpenCode가 코딩 작업에 로컬 모델을 사용할 수 있게 하는 방법을 보여줘요. opencode.json 파일을 구성하고, API 엔드포인트를 검증하고, 로컬 Docker 환경에서 제공되는 모델을 대상으로 OpenCode를 실행하게 돼요.

감사의 말: Docker는 이 가이드에 기여한 Pradumna Saraf 님께 감사를 전해요.

OpenCode 샌드박스 가이드와 달리, 이 가이드는 컨테이너화된 샌드박스에서 OpenCode를 실행하는 대신 Docker Model Runner를 백엔드로 하는 로컬 코딩 도구로 OpenCode를 사용하는 데 초점을 맞춰요.

이 가이드에서 배울 내용:

OpenCode용 코딩 모델 내려받기
Docker Model Runner를 사용하도록 OpenCode 구성하기
로컬 API 엔드포인트 검증 및 OpenCode 시작하기
더 큰 컨텍스트 윈도우가 필요할 때 gpt-oss 패키징하기

사전 요구사항

시작하기 전에 다음이 갖춰져 있는지 확인해주세요:

Docker Desktop 또는 Docker Engine 설치
Docker Model Runner 활성화
OpenCode 설치

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

$ docker desktop enable model-runner --tcp 12434

1단계: 코딩 모델 내려받기

OpenCode를 구성하기 전에 하나 이상의 모델을 내려받아주세요:

$ docker model pull ai/qwen3-coder
$ docker model pull ai/devstral-small-2

이 모델들은 큰 컨텍스트 윈도우를 지원하므로 코딩 워크플로에 잘 맞아요.

2단계: OpenCode 구성 만들기

OpenCode는 다음 위치 중 하나에서 구성을 읽어요:

~/.config/opencode/opencode.json — 전역 구성용
프로젝트 루트의 opencode.json — 프로젝트별 구성용

프로젝트 수준 구성이 전역 파일을 덮어써요.

Docker Model Runner를 가리키는 프로바이더를 추가해주세요:

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

이 구성은 Docker Model Runner를 OpenCode 프로바이더로 추가하고 두 개의 로컬 모델을 노출해요.

참고: 설정이 이전 OpenAI 호환 경로를 기대한다면 http://localhost:12434/engines/v1 을 대신 사용하세요.

3단계: 엔드포인트 검증

OpenCode를 열기 전에 Docker Model Runner에 접근 가능한지 확인해주세요:

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

이전 경로를 사용한다면 다음을 실행해주세요:

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

응답에는 Docker Model Runner를 통해 사용 가능한 모델이 나열돼야 해요.

4단계: OpenCode 시작

프로젝트 디렉터리에서 다음을 실행해주세요:

$ opencode

TUI에서 모델을 전환하려면 다음을 실행해주세요:

/models

그다음 dmr 프로바이더에서 모델을 선택해주세요.

5단계: 더 큰 컨텍스트 윈도우로 gpt-oss 패키징하기

이 단계는 선택사항이에요. 레포지토리 규모 작업에 더 큰 컨텍스트 윈도우가 필요하면 사용하세요.

gpt-oss 는 코딩에 특화된 모델보다 기본적으로 작은 컨텍스트 윈도우를 사용해요. 레포지토리 규모 작업에 사용하고 싶다면 더 큰 변형을 패키징해주세요:

$ docker model pull ai/gpt-oss
$ docker model package --from ai/gpt-oss --context-size 128000 gpt-oss:128k

그다음 OpenCode 구성에 추가해주세요:

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "dmr": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Docker Model Runner",
      "options": {
        "baseURL": "http://localhost:12434/v1"
      },
      "models": {
        "gpt-oss:128k": {
          "name": "gpt-oss:128k"
        }
      }
    }
  }
}

트러블슈팅

OpenCode가 연결할 수 없다면 Docker Model Runner 상태를 확인해주세요:

$ docker model status

OpenCode가 내 모델을 표시하지 않는다면 로컬 모델을 나열해주세요:

$ docker model ls

모델이 없다면 먼저 모델을 내려받고 opencode.json 의 모델 이름이 사용하려는 로컬 모델과 일치하는지 확인해주세요.

더 알아보기

Docker Model Runner 개요
Docker Model Runner API 참조
IDE 및 도구 통합

더 알아보기 (Learn more)

Docker Model Runner
OpenCode
Docker Model Runner API 참조