Compartir comentarios
Las respuestas se generan en base a la documentación.

Usa OpenCode con Docker Model Runner

Tabla de contenidos

Esta guía muestra cómo conectar OpenCode a Docker Model Runner para que OpenCode pueda usar modelos locales en tareas de programación. Configurarás un archivo opencode.json, verificarás el endpoint de la API y ejecutarás OpenCode con modelos servidos desde tu entorno local de Docker.

Agradecimiento

A Docker le gustaría agradecer a Pradumna Saraf por su contribución a esta guía.

A diferencia de la guía del sandbox de OpenCode, esta guía se centra en el uso de OpenCode como una herramienta de programación local respaldada por Docker Model Runner, en lugar de ejecutar OpenCode en un sandbox contenedorizado.

En esta guía, aprenderás a:

  • Descargar (pull) modelos de programación para OpenCode
  • Configurar OpenCode para usar Docker Model Runner
  • Verificar el endpoint local de la API e iniciar OpenCode
  • Empaquetar gpt-oss con una ventana de contexto más grande cuando lo necesites

Requisitos previos

Antes de comenzar, asegúrate de tener:

Si utilizas Docker Desktop, activa el acceso TCP en Settings > AI, o ejecuta:

$ docker desktop enable model-runner --tcp 12434

Paso 1: Descargar un modelo de programación

Descarga uno o más modelos antes de configurar OpenCode:

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

Estos modelos son una buena opción para los flujos de trabajo de programación porque admiten ventanas de contexto grandes.

Paso 2: Crear una configuración de OpenCode

OpenCode lee la configuración de cualquiera de estas ubicaciones:

  • ~/.config/opencode/opencode.json para una configuración global
  • opencode.json en la raíz de tu proyecto para una configuración específica del proyecto

La configuración a nivel de proyecto anula el archivo global.

Agrega un proveedor que apunte a 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"
        }
      }
    }
  }
}

Esta configuración agrega Docker Model Runner como un proveedor de OpenCode y expone dos modelos locales.

Note

Si tu configuración requiere la ruta más antigua compatible con OpenAI, utiliza http://localhost:12434/engines/v1 en su lugar.

Paso 3: Verificar el endpoint

Comprueba que Docker Model Runner sea accesible antes de abrir OpenCode:

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

Si usas la ruta antigua, ejecuta:

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

La respuesta debería listar los modelos disponibles a través de Docker Model Runner.

Paso 4: Iniciar OpenCode

Desde el directorio de tu proyecto, ejecuta:

$ opencode

Para cambiar de modelo desde la interfaz TUI, ejecuta:

/models

Luego selecciona el modelo del proveedor dmr.

Paso 5: Empaquetar gpt-oss con una ventana de contexto más grande

Este paso es opcional. Utilízalo si necesitas una ventana de contexto más grande para tareas a escala de repositorio.

gpt-oss utiliza por defecto una ventana de contexto más pequeña que los modelos enfocados en programación. Si deseas usarlo para tareas a escala de repositorio, empaqueta una variante más grande:

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

Luego agrégalo a tu configuración de 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"
        }
      }
    }
  }
}

Resolución de problemas

Si OpenCode no puede conectarse, verifica el estado de Docker Model Runner:

$ docker model status

Si OpenCode no muestra tu modelo, lista los modelos locales:

$ docker model ls

Si falta el modelo, descárgalo (pull) primero y confirma que el nombre del modelo en opencode.json coincida con el modelo local que deseas usar.

Más información