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

Usar Claude Code con Docker Model Runner

Tabla de contenidos

Esta guía muestra cómo ejecutar Claude Code con Docker Model Runner como proveedor de modelos en el backend. Apuntarás Claude Code a la API local compatible con Anthropic, ejecutarás un modelo de programación y empaquetarás gpt-oss con una ventana de contexto más grande para prompts de repositorio más largos.

Agradecimiento

Docker desea agradecer a Pradumna Saraf por su contribución a esta guía.

En esta guía, aprenderás a:

  • Descargar un modelo de programación e iniciar Claude Code con Docker Model Runner
  • Hacer que la configuración del endpoint sea persistente
  • Verificar el endpoint local de la API e inspeccionar las solicitudes
  • Empaquetar gpt-oss con una ventana de contexto más grande para prompts más largos

Prerrequisitos

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 un modelo antes de iniciar Claude Code:

$ docker model pull ai/devstral-small-2

También puedes usar ai/qwen3-coder si quieres otro modelo enfocado en programación con una ventana de contexto grande.

Paso 2: Iniciar Claude Code con Docker Model Runner

Establece ANTHROPIC_BASE_URL en tu endpoint local de Docker Model Runner cuando ejecutes Claude Code.

En macOS o Linux:

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

En Windows PowerShell:

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

Claude Code ahora envía solicitudes a Docker Model Runner en lugar de a la API alojada de Anthropic.

Paso 3: Solucionar problemas en el primer inicio

Si Claude Code no puede conectarse, comprueba el estado de Docker Model Runner:

$ docker model status

Si Claude Code no puede encontrar el modelo, enumera los modelos locales:

$ docker model ls

Si falta el modelo, descárgalo primero. Si es necesario, utiliza el nombre calificado completo del modelo, como ai/devstral-small-2.

Paso 4: Hacer que el endpoint sea persistente

Para evitar configurar la variable de entorno cada vez, añádela a tu perfil de shell:

~/.bashrc o ~/.zshrc
export ANTHROPIC_BASE_URL=http://localhost:12434

En Windows PowerShell, añádela a tu perfil de PowerShell:

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

Después de recargar tu shell, puedes ejecutar Claude Code solo con la bandera del modelo:

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

Paso 5: Verificar el endpoint de la API

Envía una solicitud de prueba para confirmar que la API compatible con Anthropic es accesible:

$ 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"}]
  }'

Para más detalles sobre el formato de la solicitud, consulta la Referencia de la API compatible con Anthropic.

Paso 6: Inspeccionar las solicitudes de Claude Code

Para inspeccionar las solicitudes que Claude Code envía a Docker Model Runner, ejecuta:

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

Esto te ayuda a depurar prompts, el uso del contexto y problemas de compatibilidad.

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

ai/gpt-oss tiene por defecto una ventana de contexto más pequeña que los modelos enfocados en programación. Si deseas usarlo para prompts 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 32000 gpt-oss:32k

Luego ejecuta Claude Code con el modelo empaquetado:

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

Más información