OpenCode con Ollama: guía paso a paso para un agente de código local
Conecta OpenCode a modelos locales o de Ollama Cloud sin mezclar interfaz, runtime, contexto y permisos del repositorio.
Contenido de la guía
OpenCode con Ollama combina un agente de código en terminal con un runtime de modelos locales o cloud. La vía oficial más rápida es ollama launch opencode, pero un entorno estable también necesita contexto suficiente, un modelo adecuado al hardware, un directorio correcto y permisos prudentes.
Inicio rápido con ollama launch opencode
Comprueba que ambas aplicaciones estén instaladas y que ollama list muestre modelos. Entra con la terminal en el repositorio que quieres analizar y ejecuta ollama launch opencode.
El launcher es el mejor primer intento: puede descargar el modelo necesario, preparar la integración, ajustar un contexto de 64K y abrir OpenCode.
Qué hace cada capa
OpenCode es el agente y la interfaz de terminal; Ollama ejecuta el modelo o conecta con Ollama Cloud. El repositorio es otro límite de confianza y sus permisos deciden qué puede leer, editar o ejecutar el agente.
Empieza en un repositorio de prueba, con Git limpio y copia de seguridad. Autoriza primero lectura y una modificación pequeña antes de permitir comandos amplios.
Qué configura el launcher
El menú interactivo muestra integraciones y modelos sugeridos. Al elegir OpenCode, la herramienta prepara la conexión con un modelo servido por Ollama.
Un inicio correcto no significa que cualquier modelo sea adecuado. Los modelos locales consumen RAM o VRAM; los modelos cloud reducen esa carga pero necesitan internet y cambian el tratamiento de los datos.
Configuración manual con opencode.json
Configura manualmente cuando el launcher no encuentre el modelo, uses otro endpoint o quieras revisar el provider como parte del proyecto. OpenCode documenta el adaptador compatible con OpenAI y el endpoint local v1.
Sustituye your-model por la etiqueta exacta de ollama list y mantenla igual en la clave y el nombre.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (local)",
"options": { "baseURL": "http://localhost:11434/v1" },
"models": { "your-model": { "name": "your-model" } }
}
}
}Contexto de 64K para repositorios
Un contexto pequeño puede empeorar las herramientas o causar errores de memoria. La documentación recomienda al menos 64K para agentes de código.
El launcher lo configura; con un modelo manual crea una variante mediante Modelfile. Si el equipo no soporta 64K, usa un modelo menor y limita archivos y alcance.
FROM your-model
PARAMETER num_ctx 65536Elegir modelo según el equipo
El mejor modelo es el que sigue respondiendo después de cargar editor, índice, terminal, pruebas y caché de contexto. Empieza pequeño y sube solo si la calidad compensa la latencia.
Los modelos cloud sirven para repositorios grandes, pero requieren conexión y una evaluación distinta de privacidad.
| Situación | Primera opción | Motivo |
|---|---|---|
| RAM limitada o gráfica integrada | Modelo local pequeño | Deja memoria para contexto, editor y pruebas |
| GPU potente o mucha memoria unificada | Modelo local mayor | Mejor razonamiento si la latencia sigue siendo útil |
| Repositorio grande o refactor difícil | Modelo cloud de Ollama | Evita el límite de memoria local; necesita internet |
| Repositorio sensible | Modelo local con permisos limitados | Mantiene la inferencia local y reduce riesgo |
Solución de problemas en orden
Si no aparecen modelos, confirma el servicio Ollama, ollama list, la URL http://localhost:11434/v1 y la etiqueta exacta.
Si se detiene al analizar el repositorio, reduce archivos o modelo. Si fallan comandos, revisa permisos y directorio antes de tocar el endpoint.
Primer flujo de trabajo seguro
Pide primero una explicación y un plan. Autoriza un cambio acotado, ejecuta una prueba concreta y revisa git diff.
No expongas Ollama públicamente sin controles de red, no incluyas secretos en prompts y recuerda que local no significa sin riesgo de comandos.
Preguntas frecuentes sobre OpenCode y Ollama
Fuentes oficiales
- Ollama OpenCode integration - Inicio rápido, configuración manual y contexto.
- Ollama launch announcement - Comportamiento oficial del launcher.
- OpenCode Ollama provider docs - Configuración oficial del provider Ollama.
- Ollama context length docs - Guía oficial sobre tamaño de contexto.
Guías locales relacionadas
- Flujo de agente local de código - Planifica contexto, permisos, parches y pruebas.
- Mejor modelo local para 16 GB - Elige un modelo que deje memoria al flujo completo.
- Cursor y Ollama - Compara el editor con el enfoque de terminal de OpenCode.
- Odysseus AI con Ollama - Resuelve problemas del runtime y el endpoint.
Actualizado: 14 de julio de 2026
Volver a Odysseus AI Wiki