OpenCode Ollama Setup: 7 comprobaciones antes de usar modelos locales

Conclusión rápida

Primero valida la cadena completa: Ollama debe responder, el modelo debe cargar y OpenCode debe verlo como proveedor. Si esta prueba falla, escribir más configuración no ayuda.

Cuando la prueba funcione, documenta el modelo, el endpoint y el tipo de tareas permitidas. Esa nota evita que cada desarrollador cree una variante distinta.

Tabla de decisión

La decisión no es ideológica. Un portátil personal necesita rapidez; un equipo necesita reproducibilidad, revisión y una ruta de rollback.

Mantén separados los temas: instalación general, comparación con Claude Code y almacenamiento de sesiones ya tienen páginas propias.

Antes de empezar

Prueba Ollama solo antes de usar OpenCode. Si el modelo es lento o no cabe en memoria, fallará aún más con contexto de repositorio.

Usa un repositorio pequeño con Git, README y una tarea segura. No empieces por despliegues, migraciones o secretos.

También conviene separar tres tipos de datos: historial de sesión, configuración del proyecto y credenciales. Usar un modelo local no elimina la necesidad de proteger `.env`, claves de proveedor, rutas privadas o fragmentos de código sensible. Si el repositorio ya excluye archivos generados y secretos, OpenCode tendrá un contexto más limpio y el modelo cometerá menos errores.

Para equipos, anota quién mantiene el modelo recomendado. Sin un responsable, el primer setup exitoso se convierte en una colección de excepciones personales: una máquina usa un modelo pequeño, otra cambia el puerto y otra depende de un servidor remoto que nadie documentó.

7 comprobaciones

Estas comprobaciones dividen el problema en capas: servicio, modelo, configuración, lectura, edición, comandos y notas de error.

1. Confirm the service Run Ollama directly and make sure the default local service is reachable before opening OpenCode.
2. Pull the model Use a model that is appropriate for coding and fits your memory budget.
3. Choose launch or config Use `ollama launch opencode` for the first proof, then document `opencode.json` if the workflow will be reused.
4. Select the model in OpenCode Open the model picker or equivalent provider selection and confirm the Ollama model is visible.
5. Run a read-only task Ask OpenCode to summarize a small file before allowing edits.
6. Run a low-risk edit Change documentation or a test fixture and inspect the Git diff.
7. Record failure notes Save the model name, port, OS, shell, and fix for any timeout, missing model, or spawn error.

Ejemplo de configuración

Verifica siempre la documentación oficial. La idea estable es apuntar OpenCode al endpoint compatible con OpenAI de Ollama.

No mezcles ejemplos locales con tokens reales de proveedores cloud.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      }
    }
  }
}

Resolución de problemas

Si el modelo no aparece, confirma primero que Ollama lo ejecuta directamente. Luego revisa puerto, base URL y nombre del modelo.

Si responde pero edita mal, reduce el alcance o usa un modelo más fuerte para cambios difíciles.

Cuando el servidor responde pero OpenCode no, guarda una prueba mínima: comando usado, modelo, puerto, sistema operativo y captura del error en texto. Esa evidencia permite comparar con otra máquina sin tocar todavía el repositorio real.

Si la latencia es el problema, no ajustes permisos ni prompts antes de medir. Prueba una pregunta corta, una lectura de archivo y una edición pequeña. Si todas son lentas, el cuello de botella es el modelo o el hardware; si solo falla la edición, revisa contexto y permisos.

Cuándo no usar Ollama por defecto

No conviertas Ollama en proveedor predeterminado si el hardware es lento, el contexto queda corto o nadie mantiene la configuración.

Una combinación suele ser mejor: modelo cloud para ediciones difíciles y Ollama para explicación local o pruebas privadas.

Una decisión razonable puede ser no usar Ollama para todo. Mantenerlo como proveedor secundario reduce riesgo: sirve para explicar código privado, probar ideas fuera de línea y aprender el flujo local, mientras las ediciones críticas siguen en un modelo con mejor rendimiento.