OpenCode - setup y uso

Montaje de un agente de código por línea de comandos que reparte el trabajo entre un modelo grande en la nube y varios modelos pequeños en local. La idea es simple: lo caro se reserva para lo que aporta, y el trabajo de barrido, exploración y lectura de ficheros lo hace una GPU propia.

Arquitectura

Pieza	Rol	Donde corre
Orquestador	Razona, planifica, edita código, decide que delegar	Modelo grande por API
Subagentes locales	Explorar el repositorio, resumir, buscar, clasificar	llama-server en local
Subagente de visión	Leer capturas, diagramas y PDF escaneados	Modelo visión local, bajo demanda

El orquestador no lee ficheros enteros para “entender” el proyecto: delega esa lectura en un modelo local y recibe solo el resumen. Es la diferencia entre pagar 50.000 tokens de contexto y pagar 2.000.

Requisitos

• GPU con VRAM suficiente para el modelo local que se elija. Regla práctica: un modelo de 7B en Q5 ocupa unos 5-6 GB; uno de 27B en cuantización agresiva ronda los 13-14 GB. La cuenta completa está en VRAM - planificacion de modelos locales.
• Un ejecutable de llama-server y los GGUF descargados en una carpeta por modelo.
• RAM de sistema por encima de la VRAM si se quiere cargar el modelo desde disco sin penalización.

Un modelo por puerto

Cada modelo se sirve en su propio puerto de llama-server y se declara en la configuración como un proveedor local más. El patron:

Papel	Puerto	Cuando esta levantado
Modelo principal local	<PUERTO_1>	Siempre, es el que usan los subagentes
Modelo de visión	<PUERTO_2>	Solo cuando el orquestador delega una imagen
Modelo alternativo	<PUERTO_3>	Apagado; se levanta para comparar o si el principal falla

Lo importante no es el número de puerto, es la regla: un modelo pesado y un modelo de visión no caben a la vez en la mayoría de equipos de laboratorio. Por eso el de visión se arranca y se para bajo demanda, y el orquestador sabe que no puede pedirle trabajo mientras el principal esta cargado.

Configuración

El fichero opencode.jsonc en ~/.config/opencode/ define proveedores, agentes, MCP y permisos. Esqueleto mínimo:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://127.0.0.1:<PUERTO_1>/v1" },
      "models": { "<MODELO_LOCAL>": { "name": "<MODELO_LOCAL>" } }
    }
  },
  "agent": {
    "explore": { "model": "local/<MODELO_LOCAL>", "mode": "subagent" },
    "vision": { "model": "local/<MODELO_VISION>", "mode": "subagent" }
  },
  "permission": {
    "external_directory": { "deny": ["<RUTA_NO_ACCESIBLE>"] }
  }
}

Dos reglas de higiene que evitan sustos:

• Todo lo que sea credencial va en variables de entorno, nunca en el JSON: TAVILY_API_KEY, VIRUSTOTAL_API_KEY y similares se leen del entorno del proceso.
• Los directorios que el agente no debe tocar se deniegan por configuración, no confiando en el prompt. Si existe una carpeta con datos de clientes, se bloquea ahi.

MCP: que aporta cada tipo

Los servidores MCP amplian las herramientas del agente. Cuatro categorias que si merecen la pena:

Tipo	Para que	Coste
Memoria persistente	Grafo de entidades entre sesiones (servicio, host, interlocutor)	Gratis, local
RAG del vault	Busqueda semantica sobre notas propias	Gratis, local
OSINT	DNS, WHOIS, certificados, geoIP, BGP, Wayback	Capa gratuita amplia
Threat intel	Reputación de IP, hashes y dominios	Capa gratuita limitada

El resto suele ser ruido: cada MCP añade herramientas al prompt y consume contexto. Cinco o seis bien elegidos rinden más que quince.

Skills

Las skills son procedimientos que el agente carga cuando la petición encaja. Viven en ~/.config/opencode/skills/<nombre>/SKILL.md con un frontmatter que declara cuando se activan.

Dos ejemplos de criterio:

• Una skill de consulta SPL se activa con “spl”, “busqueda en splunk” o “alerta”. Evita que el agente improvise sintaxis y le obliga a usar los indices reales.
• Una skill de mapeo MITRE se activa con “ATT&CK” o “técnica” y devuelve ID, descripción y detección, sin releer el vault.

Regla: una skill por tarea repetible. Si una instrucción se acaba copiando en cada conversación, es una skill.

Visión bajo demanda

El análisis de imagenes es el caso típico de recurso que no puede estar siempre cargado. El ciclo es siempre el mismo:

1. El orquestador detecta que la petición necesita leer una imagen.
2. Para el modelo principal para liberar VRAM.
3. Arranca el modelo de visión y procesa la imagen.
4. Recibe la descripción en texto.
5. Apaga el modelo de visión y reactiva el principal.

El coste real de este ida y vuelta es de uno a dos minutos, y se nota en la conversación. Por eso conviene agrupar las imagenes: una sesión de veinte capturas de una vez, no una cada diez mensajes.

RAG del vault, en dos niveles

1. Referencia con busqueda de texto: el agente busca con rg sobre los .md, filtrando por carpeta y por extensión. Barato, exacto, y suficiente cuando se sabe que palabra buscar.
2. Busqueda semantica: un MCP indexa las notas con embeddings multilingues y devuelve los fragmentos más parecidos. Sirve cuando no se sabe la palabra exacta (“técnicas de evasión de antivirus” sin saber si la nota habla de “evasión” o de “bypass”).

El índice hay que reconstruirlo cuando el vault cambia de forma significativa: notas nuevas en bloque, renombrados o reestructuración de carpetas. Si no se reindexa, la busqueda semantica devuelve fragmentos que ya no existen.

Delegación a subagentes

Cuatro reglas que evitan el 90% de los problemas:

• Delegar lectura, no decisión. El modelo local explora y resume; el orquestador decide.
• Peticiones cerradas. “Lista los ficheros que definen el esquema y di que tablas usa” funciona; “entiende el proyecto” no.
• Contexto mínimo. Se pasa la ruta y el objetivo, no el contenido entero.
• Modelo pequeño para clasificar, grande para razonar. Si la tarea se resuelve con una etiqueta, no hace falta el modelo caro.

Limitaciones

• Un modelo local pequeño inventa rutas y nombres de función cuando el repositorio es grande. Verificar siempre lo que devuelve antes de usarlo.
• El cambio de modelo por VRAM introduce latencia perceptible; para trabajo interactivo conviene un solo modelo local.
• El contexto útil de un modelo local cuantizado es menor de lo que anuncia la ficha: por encima de cierta longitud empieza a perder el hilo.
• Los MCP con capa gratuita se agotan y devuelven errores que el agente interpreta como “sin resultados”. Comprobar cuota antes de concluir que un dominio no tiene nada.