OpenCode admite más de 75 proveedores LLM a través de su directorio de proveedores, pero los proveedores personalizados siguen siendo importantes. Son la manera de añadir un gateway, un entorno de ejecución local, un endpoint de inferencia interno o un modelo que aún no está en el directorio.

El proceso es sencillo: guarda una credencial, añade un bloque de proveedor, reinicia OpenCode y selecciona el modelo desde /models.

¿Quieres configurar Haimaker específicamente? Sáltate los pasos manuales: ejecuta npx -y @haimaker/connect --opencode y la CLI escribe el bloque de proveedor y guarda tu credencial automáticamente (añade --project para una configuración a nivel de proyecto). La guía paso a paso de abajo es el método general para cualquier proveedor compatible con OpenAI: Ollama, LM Studio, un gateway interno o cualquier cosa que aún no esté en el directorio. Consulta la guía de conexión para la vía de un solo comando.

Cuándo usar un proveedor personalizado

Usa un proveedor personalizado cuando el modelo o el endpoint no esté ya disponible en la lista de proveedores integrados de OpenCode.

Ejemplos habituales:

  • Haimaker: una sola clave de API para varias familias de modelos a través de un gateway compatible con OpenAI.
  • Ollama: modelos locales en http://localhost:11434/v1.
  • LM Studio: modelos locales en http://127.0.0.1:1234/v1.
  • Gateways internos: endpoints compatibles con OpenAI alojados en la empresa.
  • Nuevos proveedores: cualquier servicio que utilice la API de chat compatible con OpenAI antes de que el directorio de OpenCode se actualice.

Si el proveedor ya existe en OpenCode, usa primero la opción integrada. La configuración personalizada es más útil cuando necesitas una URL base personalizada, un gateway o un modelo que falta en la lista por defecto.

Paso 1: Añadir la credencial

La documentación actual de OpenCode remite a los usuarios a opencode auth login para las credenciales de proveedor. Para un proveedor personalizado compatible con OpenAI, elige Other, introduce un ID de proveedor y pega la clave de API:

opencode auth login

Elige un ID de proveedor corto que también usarás en la configuración. Por ejemplo:

haimaker
ollama
mygateway

OpenCode almacena las credenciales en:

~/.local/share/opencode/auth.json

Puedes editar ese archivo manualmente cuando sea necesario, pero usar opencode auth login evita errores en el formato de la clave.

Paso 2: Configurar el proveedor

Abre o crea tu configuración de OpenCode. Según tu caso, puede ser opencode.json en el proyecto o un archivo global en ~/.config/opencode/.

Añade un bloque provider con el mismo ID de proveedor que usaste durante la autenticación. Aquí tienes el patrón usando haimaker.ai como ejemplo:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "z-ai/glm-4.6": {
          "name": "GLM 4.6"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

Qué hace cada campo:

  • npm: el adaptador del SDK. Para cualquier API compatible con OpenAI, usa @ai-sdk/openai-compatible. OpenCode carga el adaptador bajo demanda.
  • name: el nombre que se muestra en OpenCode.
  • options.baseURL: la URL base de la API del proveedor. Debe terminar en /v1 o en el prefijo de versión que utilice el proveedor.
  • models: los modelos que quieres tener disponibles en OpenCode. Las claves deben coincidir exactamente con lo que la API del proveedor acepta en el campo model de una solicitud de completado.

Puedes añadir tantos proveedores personalizados como quieras, cada uno como una entrada separada dentro de provider.

Paso 3: Reiniciar y verificar

Es posible que OpenCode no detecte los cambios de proveedor hasta que se reinicie. Ciérralo por completo, vuelve a iniciarlo y ejecuta:

/models

Deberías ver el nombre del proveedor y los modelos configurados. Selecciona uno y envía un prompt breve antes de usarlo con código real.

Ejemplo completo: gateway de Haimaker

Usa esta configuración cuando quieras un único endpoint compatible con OpenAI para varias familias de modelos:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6"
        },
        "openai/gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

Ventajas de esta configuración: OpenCode ve un solo proveedor, mientras que Haimaker gestiona el acceso a varias familias de modelos upstream. Así tu configuración de OpenCode queda más compacta y cambiar de modelo es menos engorroso.

Ejemplo completo: proveedor local con Ollama

Ollama expone un endpoint local compatible con OpenAI en http://localhost:11434/v1:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "Qwen3 Coder 30B"
        },
        "gemma4:e4b": {
          "name": "Gemma 4 E4B"
        }
      }
    }
  }
}

Descarga los modelos antes de iniciar OpenCode:

ollama pull qwen3-coder:30b
ollama pull gemma4:e4b

Si OpenCode requiere autenticación para el proveedor local, ejecuta opencode auth login, elige Other, usa ollama como ID de proveedor e introduce cualquier clave no vacía, por ejemplo ollama. Ollama no valida las claves de API locales.

Errores comunes y soluciones

El proveedor no aparece en /models

Comprueba cuatro cosas:

  1. El ID de proveedor de opencode auth login coincide con la clave del proveedor en la configuración.
  2. El archivo de configuración es JSON o JSONC válido.
  3. Has reiniciado OpenCode después de editar la configuración del proveedor.
  4. El modelo está incluido en el objeto models del proveedor.

La autenticación falla en la primera solicitud

La credencial falta o está asociada a un ID de proveedor incorrecto. Ejecuta:

opencode auth list

Después confirma que el ID de proveedor coincide exactamente con tu configuración. No incluyas Bearer en el campo de la clave.

El modelo aparece pero las solicitudes fallan

Probablemente el ID del modelo no coincide con lo que espera la API upstream. Los proveedores personalizados pasan los IDs de modelo sin modificarlos. Si tu configuración dice qwen/qwen3-coder, la API debe aceptar exactamente qwen/qwen3-coder.

Para Haimaker, prueba la clave y el endpoint:

curl https://api.haimaker.ai/v1/models \
  -H "Authorization: Bearer your-haimaker-api-key"

Para Ollama, comprueba los modelos locales:

ollama list

Usa el nombre exacto del modelo que aparece en esa salida.

Las llamadas a herramientas fallan con modelos locales

Los modelos locales son más sensibles a los límites de contexto y al formato de las llamadas a herramientas. Empieza con un modelo que se desenvuelva bien en la programación con agentes, como Qwen3 Coder, y mantén un contexto moderado. La documentación de OpenCode también recomienda aumentar num_ctx de Ollama cuando las llamadas a herramientas no funcionan.

Los proveedores integrados han dejado de funcionar

Probablemente hayas reemplazado más configuración de la que pretendías. Mantén los proveedores personalizados dentro del objeto provider y evita eliminar entradas de proveedores existentes. En caso de duda, haz el cambio de configuración más pequeño posible: añade un ID de proveedor y un modelo, reinicia, prueba y luego añade más.

La configuración práctica

Para la mayoría de los usuarios de OpenCode, la configuración ideal es:

  1. Haimaker para modelos en la nube y enrutamiento con una sola clave.
  2. Ollama para trabajo local privado.
  3. Un modelo premium de respaldo para depuración compleja y refactorizaciones multiarchivo.

Así tienes privacidad local cuando la necesitas, modelos en la nube económicos para el trabajo del día a día y un modelo más potente cuando la tarea de programación requiere mucha atención.

USA HAIMAKER CON OPENCODE

Para la configuración local, consulta Usar Ollama con OpenCode. Para comparativas más amplias de modelos locales, consulta Los mejores modelos de Ollama para agentes de programación.