Cuando OpenCode con Ollama deja de funcionar, comprueba el endpoint del servidor y el ID exacto del modelo antes de cambiar de modelo. Si ambas comprobaciones son correctas, prueba una edición pequeña de archivo para distinguir un problema de llamada a herramientas de un problema de conexión. Que un modelo responda a una solicitud de chat solo significa que ha superado la primera fase del flujo de trabajo de un agente de código.
Esta guía parte de que Ollama y OpenCode ya están instalados. Para la instalación y configuración del proveedor, consulta la guía de configuración de Ollama con OpenCode. El procedimiento descrito aquí aísla los fallos sin modificar repetidamente tu configuración actual.
Identifica qué solicitud está fallando
Un fallo de OpenCode puede producirse antes de la inferencia, durante la generación o cuando se ejecuta una herramienta. Comprueba esas fases por separado. Una conexión rechazada indica un problema distinto al de un modelo que devuelve un párrafo con apariencia de JSON. Registra el endpoint, el modelo seleccionado y el error antes de cambiar una configuración, para poder determinar si el cambio surtió efecto.
| Observación | Siguiente comprobación | Qué demuestra el resultado |
|---|---|---|
| Conexión rechazada | Solicita /api/version en el host y puerto configurados | Si ese endpoint de Ollama es accesible |
| Modelo no encontrado | Lee /v1/models y compara el ID exacto | Si el modelo solicitado existe en ese servidor |
| El chat funciona, los archivos no cambian | Inspecciona las llamadas a herramientas y los resultados de permisos | Si OpenCode intentó y completó una acción |
| Ediciones pequeñas funcionan, tareas grandes fallan | Inspecciona el contexto asignado y los registros de ejecución | Si la tarea más grande encuentra un límite medible |
| Local funciona, la nube se cuelga | Prueba las dos rutas por separado | Si el fallo es específico de la ruta en la nube |
Registra las versiones antes de reproducir un fallo:
opencode --version
ollama --version
Las comprobaciones locales de este artículo se realizaron con OpenCode 1.19.4 y Ollama 0.32.9 en un Apple M3 Ultra con 96 GB de memoria unificada. Ese hardware puede ejecutar nuestro modelo elegido de 31B; no es una recomendación de memoria para un portátil más pequeño. Para la selección de modelos en otro hardware, consulta la guía de modelos de código para Ollama.
Comprueba el endpoint antes de cambiar el modelo
Solicita el mismo host y puerto que utiliza OpenCode. Un servidor local en 127.0.0.1:11434 y un servidor en 127.0.0.1:11435 son endpoints diferentes. Si la solicitud falla, repara primero el servidor o la dirección. Cambiar el modelo no puede reparar una conexión de red rechazada.
curl --fail-with-body --max-time 5 \
http://127.0.0.1:11434/api/version
curl --fail-with-body --max-time 5 \
http://127.0.0.1:11434/v1/models
Una respuesta de versión confirma que Ollama ha respondido. Una respuesta con la lista de modelos confirma qué IDs de modelo expone ese servidor. Una lista vacía significa que el servidor es accesible pero no tiene modelos listados; es distinta de un error de conexión.
Si Ollama está detenido, inicia la aplicación o ejecuta su servidor en un terminal:
ollama serve
Si el puerto ya está ocupado, comprueba qué servidor está en ejecución en lugar de iniciar otra copia. Una instalación remota de Ollama requiere su dirección remota; 127.0.0.1 siempre se refiere a la máquina que ejecuta el cliente.
La documentación de integración de OpenCode de Ollama utiliza una URL base compatible con OpenAI que termina en /v1. Mantén ese sufijo en la configuración del proveedor de OpenCode. Las rutas de diagnóstico nativas como /api/version quedan fuera de ella.
Haz coincidir el modelo configurado con el ID exacto del servidor
Utiliza el ID de modelo devuelto por el servidor, incluida su etiqueta. Un modelo descargado en un servidor Ollama no está disponible para otro a menos que este también lo tenga descargado. Comprueba el proveedor seleccionado, su URL base y la declaración del modelo de forma conjunta antes de reintentar la solicitud.
Esta es la estructura de proveedor utilizada en nuestras comprobaciones con OpenCode 1.19.4:
{
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"options": {
"baseURL": "http://127.0.0.1:11434/v1"
},
"models": {
"gemma4:31b": {
"name": "Gemma 4 31B",
"limit": {
"context": 65536,
"output": 2048
}
}
}
}
}
}
Sustituye gemma4:31b por un ID que tu servidor realmente liste. El ejemplo no descarga ese modelo. El selector completo de OpenCode combina el nombre del proveedor y el ID del modelo:
opencode run -m ollama/gemma4:31b "Reply with one short sentence."
Solicitamos deliberadamente un modelo ausente a través del endpoint compatible de Ollama y recibimos un HTTP 404 con un not_found_error. Ese resultado indica un error de selección de modelo. No indica una falta de memoria ni un fallo en el parser de herramientas.
Las configuraciones también pueden provenir de varias ubicaciones. La documentación de configuración de OpenCode describe cómo se fusionan los ajustes. Inspecciona la configuración resuelta localmente cuando un valor parezca ignorado:
opencode debug config
La configuración resuelta puede contener credenciales. Extrae los ajustes relevantes del proveedor antes de compartir un informe de diagnóstico y elimina claves o detalles de cuenta no relacionados.
Verifica una acción con un entorno de pruebas de código desechable
Comprueba el archivo modificado y ejecuta su prueba tú mismo. Dale a OpenCode un archivo mínimo con un bug conocido, pídele que lo repare y ejecuta una comprobación independiente después. Esto prueba el acceso a archivos, la edición y la ejecución, manteniendo el diagnóstico lo bastante pequeño como para inspeccionarlo.
Crea un directorio nuevo y entra en él:
mkdir opencode-ollama-check
cd opencode-ollama-check
cat > add.mjs <<'JS'
export function add(a, b) {
return a - b;
}
JS
cat > check.mjs <<'JS'
import { add } from './add.mjs';
if (add(2, 3) !== 5) throw new Error('Expected add(2, 3) to return 5');
console.log('PASS');
JS
node check.mjs
La primera comprobación debería fallar. Copia tu configuración de proveedor probada en este directorio desechable y ejecuta:
opencode run -m ollama/gemma4:31b \
"Read add.mjs. Fix add so it adds its arguments. Run node check.mjs."
node check.mjs
Inspecciona add.mjs tú mismo. Un mensaje de éxito del modelo es insuficiente si el archivo sigue restando o la comprobación independiente falla. Mantén visibles los avisos de permisos para poder distinguir una edición denegada de una llamada a herramienta ausente. Durante nuestras comprobaciones, macOS resolvió el entorno de pruebas bajo /private/tmp mientras una herramienta solicitaba su alias /tmp. OpenCode trató la ruta con alias como externa y la rechazó en una ejecución no interactiva. Usar el directorio resuelto y rutas de archivo relativas permitió que el entorno de pruebas se ejecutara con permisos de alcance limitado.
Para una inspección más profunda, la CLI de OpenCode admite salida JSON:
opencode run --format json -m ollama/gemma4:31b \
"Read add.mjs and explain the implementation."
Busca una herramienta ejecutada y su resultado. Un texto que contenga un nombre de función o un objeto JSON no demuestra por sí mismo que OpenCode haya ejecutado algo. Tras corregir el endpoint y los permisos del entorno de pruebas, una ejecución de reparación leyó el entorno de pruebas, cambió la resta por una suma y superó una comprobación independiente con Node. Una segunda ejecución superó la misma comprobación tras sustituir el ID de modelo deliberadamente ausente. En nuestra prueba directa de API por separado, Gemma 4 31B devolvió una llamada read_file estructurada con 65.536 de contexto. Ese único resultado valida el formato de respuesta de la prueba, no la fiabilidad en tareas de código.
Comprueba el contexto que Ollama asignó realmente
El límite de contexto que declara OpenCode y la asignación en tiempo de ejecución de Ollama deben coincidir. Aumentar un número en la configuración del cliente no demuestra que el servidor haya asignado más contexto. Inspecciona el modelo en ejecución durante una solicitud y luego compara su contexto real con el prompt de la tarea y el historial de herramientas.
La documentación de contexto de Ollama recomienda al menos 64.000 tokens para herramientas y agentes de código. También explica que asignaciones mayores consumen más memoria. Un servidor iniciado manualmente puede establecer una asignación explícita:
OLLAMA_CONTEXT_LENGTH=65536 ollama serve
Establece esa variable en el proceso que ejecuta Ollama. Exportarla solo en el terminal que ejecuta OpenCode no reconfigura una aplicación Ollama ya en ejecución. Utiliza la configuración de contexto de la aplicación si esta gestiona tu servidor.
Mientras el modelo está cargado, inspecciónalo:
ollama ps
Comprueba las columnas CONTEXT y PROCESSOR. Si Ollama utiliza un host o puerto personalizado, apunta la CLI a ese servidor también. La presión de memoria, la descarga a CPU, el truncamiento y los fallos de formato de herramientas deben verificarse por separado; una respuesta lenta por sí sola no permite determinar cuál de ellos se produjo.
Si tu hardware no puede admitir el contexto requerido, elige un modelo más pequeño que admita herramientas y repite el mismo entorno de pruebas. Evita comparar dos modelos con tareas diferentes y atribuir después la diferencia a la calidad del modelo.
Prepara un informe de fallo útil
Un informe útil permite a otro desarrollador reproducir la misma solicitud. Incluye las versiones, la configuración del proveedor sanitizada, la etiqueta exacta del modelo, el contexto asignado y el entorno de pruebas más pequeño que sigue fallando. Registra si una solicitud directa tiene éxito y si OpenCode alcanza el servidor del modelo. Esos detalles ayudan a los mantenedores a localizar el fallo.
La guía de resolución de problemas de OpenCode explica cómo localizar los registros. En la versión probada, este comando identifica las rutas de datos y registros configuradas:
opencode debug paths
Mantén separados los resultados locales y en la nube. Una prueba de código local no puede validar la autenticación o disponibilidad de Ollama Cloud, y una interrupción en la nube no demuestra una regresión local en el uso de herramientas. Del mismo modo, una incidencia antigua que describe el mismo síntoma no prueba que su solución propuesta se aplique a tu versión instalada.
Si el entorno de pruebas tiene éxito pero tu tarea de repositorio falla, conserva el entorno de pruebas funcional y añade complejidad gradualmente: otro archivo, una entrada más grande o una secuencia de herramientas más larga. El primer cambio que reproduce el fallo es más útil que reinstalar ambas aplicaciones sin una comparación.
Para una configuración de proveedor separada después de terminar el diagnóstico local, la guía de proveedor personalizado de OpenCode cubre la configuración de Haimaker. Mantén las pruebas locales privadas en tu entorno local; cambiar de proveedor es un paso opcional que puedes dar cuando la carga de trabajo lo permita.
Preguntas frecuentes
¿Significa que las herramientas de OpenCode funcionarán si el chat con Ollama responde correctamente?
No. Una respuesta de chat demuestra que el modelo puede generar texto. OpenCode también necesita llamadas a herramientas estructuradas, permiso para ejecutarlas y contexto suficiente para la tarea. Verifica una edición real de archivo y su resultado de prueba.
¿Aumentar el límite de contexto de OpenCode asigna más memoria en Ollama?
Un límite de contexto declarado en OpenCode no demuestra que Ollama haya asignado ese contexto. Configura el servidor Ollama e inspecciona el modelo en ejecución con ollama ps. Un contexto mayor también incrementa los requisitos de memoria.
¿Debo reinstalar todo cuando un modelo de Ollama desaparece de OpenCode?
Empieza comparando los IDs de modelo que devuelve Ollama con el modelo declarado en tu configuración de OpenCode. Comprueba el endpoint y el proveedor seleccionado antes de reinstalar cualquiera de las dos aplicaciones.