Instalación OpenCode, OmniRoute y Ponytail

El desarrollo asistido por IA empezó siendo un autocompletado inteligente del código a nivel de línea. Pasó a ser una "segunda opinión" que revisaba el código a nivel de fichero y sugería cambios. En los últimos dos años se ha dado un importante paso más allá hasta llegar al paradigma actual, el desarrollo agéntico: un agente que trabaja a nivel de proyecto, edita ficheros, ejecuta comandos, realiza por sí solo los cambios que antes solo se sugerían, lanza los tests e itera hasta cerrar la tarea. El problema es que todas las herramientas comerciales de este tipo (Claude Code, Cursor, Devin, Copilot, Codex, etc.) comparten dos limitaciones: una suscripción mensual y unas cuotas que se agotan justo cuando la sesión se está poniendo interesante. Porque aquí no consideramos el uso por medio de API que para el ámbito personal resulta inasequible.

Hay además un tercer problema, más silencioso pero también caro: los agentes tienden a sobre-construir. Se les pide un selector de fechas y acaban instalando una librería, escribiendo un componente envoltorio y una hoja de estilos. Cada línea de más se paga dos veces, en tokens al generarla y en tokens cada vez que vuelve a entrar en el contexto.

En este artículo se describe cómo montar un entorno de desarrollo agéntico completo combinando tres proyectos de código abierto que resuelven precisamente estas limitaciones:

• OpenCode: el agente de programación en terminal.
• OmniRoute: el router/gateway de modelos que alimenta al agente.
• Ponytail: el skill que impone al agente disciplina de código mínimo.

Descripción de los productos

OpenCode

OpenCode es un agente de programación que se ejecuta en la terminal (TUI), de código abierto y, lo más importante para nuestro propósito, agnóstico respecto al proveedor de modelos. A diferencia de Claude Code (atado a Anthropic) o Codex (atado a OpenAI), OpenCode permite configurar cualquier proveedor, incluidos los que exponen una API compatible con OpenAI, que a día de hoy son prácticamente todos.

Sus características principales:

• Interfaz de terminal con sesiones persistentes, gestión de contexto y undo de los cambios aplicados.
• Acceso a herramientas: lectura y escritura de ficheros, ejecución de comandos, búsqueda en el repositorio, control de versiones.
• Fichero de contexto por proyecto (AGENTS.md) que se genera con /init y que sirve para instruir al agente sobre las convenciones del repositorio.
• Soporte de MCP (Model Context Protocol) para añadir herramientas externas.
• Modo CLI no interactivo (opencode run "...") para automatizaciones y scripts.
• Agentes especializados y modos de trabajo (por ejemplo un modo plan que no hace cambios pensado para la fase de planificación previa).

OmniRoute

OmniRoute es un gateway de IA local y de código abierto. Se instala en la propia máquina (o en un VPS), levanta un endpoint compatible con la API de OpenAI y un panel web de administración, y desde ahí enruta cada petición hacia cualquiera de los cientos de proveedores que tiene catalogados, de los que unos 90 disponen de capa gratuita.

Lo interesante no es el catálogo en sí, sino lo que hace con él:

• Enrutado automático: usando el modelo virtual auto, OmniRoute construye un combo con los proveedores que tengamos conectados y elige uno en cada petición según su puntuación en vivo. Existen variantes: auto/coding (calidad para generar código), auto/fast (menor latencia), auto/cheap (menor coste por token) y auto/offline (mayor margen de cuota disponible).
• Fallback en cascada: cuando un proveedor devuelve un error de cuota, un rate limit o un 4xx-5xx, la petición se reintenta contra el siguiente proveedor de la lista de forma transparente para el cliente. Esto es lo que evita el clásico "se acabó tu cuota, vuelve en cinco horas".
• Compresión de contexto: una batería de motores que recortan el prompt (deduplicación, poda de historial, compactado de ficheros) y que permiten ahorros importantes de tokens, especialmente valiosos cuando se trabaja contra capas gratuitas medidas en tokens/día.
• Panel de control en http://localhost:20128 con estadísticas de uso por proveedor, gestión de claves API y configuración asistida de las herramientas CLI más habituales.
• Local-first: las claves de los proveedores y el tráfico se quedan en la máquina; OmniRoute no es un servicio en la nube al que haya que suscribirse.

Ponytail

Ponytail es un skill, es decir un conjunto de instrucciones que se inyectan en el contexto del agente en cada turno para modificar su comportamiento. Su cometido es uno solo, combatir la sobre-ingeniería, y lo hace obligando al agente a recorrer una escalera de decisión antes de escribir una sola línea, deteniéndose en el primer peldaño que resuelva el problema:

1. ¿Esto necesita existir?          → no: no lo hagas (YAGNI)
2. ¿Ya está en este repositorio?    → reutilízalo, no lo reescribas
3. ¿Lo hace la librería estándar?   → úsala
4. ¿Es una función nativa de la plataforma? → úsala
5. ¿Hay una dependencia ya instalada?       → úsala
6. ¿Cabe en una línea?              → una línea
7. Sólo entonces: lo mínimo que funcione

El ejemplo canónico del proyecto, al que hacíamos referencia en la introducción, lo resume bien: ante la petición de un selector de fechas, el resultado deja de ser una librería más un componente y pasa a ser, gracias a Ponytail, <input type="date">.

Dos matices importantes:

• La escalera se aplica después de entender el problema, no en lugar de entenderlo. El agente sigue obligado a leer el código afectado y a seguir el flujo real antes de elegir peldaño. Perezoso con la solución, nunca con la lectura.
• Hay cuatro cosas que nunca se recortan: validación en las fronteras de confianza, gestión de pérdida de datos, seguridad y accesibilidad. La regla no es "menos tokens", es "sólo lo que la tarea necesita".

Según el benchmark que publica el proyecto (sesiones reales de un agente sobre un repositorio FastAPI + React, con y sin el skill), los resultados frente a la línea base son un 54% menos de líneas de código, un 22% menos de tokens, un 20% menos de coste y un 27% menos de tiempo, sin penalización en las comprobaciones de seguridad. Como siempre con los benchmarks, conviene tomarlos como orden de magnitud y no como promesa: el ahorro es enorme donde hay una trampa clara de sobre-construcción y casi nulo donde el código ya era mínimo.

Ponytail funciona en un buen número de agentes (Claude Code, Codex, Copilot CLI, Gemini CLI, Cursor, Devin...), y OpenCode es uno de los que tiene soporte de primera clase mediante plugin.

El valor de la combinación

Por separado cada pieza es útil, pero es al combinarlas cuando desaparecen las limitaciones que mencionábamos al principio. Cada una cubre una capa distinta y no se solapan: OmniRoute decide quién responde, OpenCode decide qué se hace, y Ponytail decide cuánto código se escribe.

Problema	Cómo lo resuelve la combinación
Suscripción mensual	OpenCode es gratuito y OmniRoute se conecta a capas gratuitas de decenas de proveedores. El coste de entrada es 0 €.
Agotamiento de cuota	El fallback de OmniRoute salta al siguiente proveedor sin interrumpir la sesión del agente.
Dependencia de un proveedor	El agente sólo conoce un endpoint (localhost:20128/v1); cambiar de modelo o de proveedor no requiere tocar el agente.
Consumo excesivo de tokens	Los motores de compresión de OmniRoute reducen el tamaño de los prompts que envía el agente, que suelen ser grandes por el contexto del repositorio.
Falta de visibilidad del gasto	El panel de OmniRoute centraliza el consumo de todos los proveedores y de todas las herramientas conectadas.
Código sobredimensionado	Ponytail recorta lo que el agente construye, lo que a su vez reduce el código a revisar, mantener y volver a meter en el contexto en las siguientes sesiones.

La combinación de las tres piezas tiene un efecto multiplicador sobre la cuota disponible: Ponytail reduce los tokens de salida (menos código generado), la compresión de OmniRoute reduce los de entrada (menos contexto enviado) y el fallback aprovecha la cuota de todos los proveedores conectados.

Un beneficio adicional: como OmniRoute expone un endpoint estándar, el mismo gateway sirve simultáneamente a OpenCode en la terminal, a una extensión de VSCode o a cualquier otro cliente compatible con la API de OpenAI. Se configura una vez y lo aprovecha todo el entorno.

Modelos modestos, mejores resultados

Un efecto colateral interesante de Ponytail es que hace más viable trabajar con los modelos gratuitos, que suelen ser más pequeños. Cuanto menor es el volumen de código que se le pide generar a un modelo, menos oportunidades tiene de equivocarse; el skill reduce precisamente el tamaño de lo que se le encarga en cada paso.

Sobre las capas gratuitas

Las condiciones de las capas gratuitas de los proveedores cambian con frecuencia y algunas desaparecen sin previo aviso. La ventaja del enfoque con OmniRoute es que esos cambios se absorben en el gateway (conectando otro proveedor) sin tocar la configuración del agente. Conviene también revisar las políticas de privacidad de cada proveedor gratuito antes de enviarles el código de un proyecto sensible.

Instalación

Todo el procedimiento se ha realizado sobre Linux. En Windows y MacOS los pasos son equivalentes, cambiando la forma de instalar los requisitos.

Los tres proyectos se distribuyen vía npm, así que el único requisito común es disponer de Node.js reciente (versión 22 o superior).

node --version

Instalación de OpenCode

La forma recomendada es el script oficial de instalación:

curl -fsSL https://opencode.ai/install | bash

Alternativamente, según el sistema:

npm install -g opencode-ai                  # npm (también bun, pnpm o yarn)
brew install anomalyco/tap/opencode         # MacOS / Linux con Homebrew
sudo pacman -S opencode                     # Arch Linux (repositorios oficiales)
paru -S opencode-bin                        # Arch Linux (AUR, última versión)

Comprobamos la instalación lanzando el agente dentro de cualquier directorio:

opencode

En este punto OpenCode arrancará pero pedirá credenciales de algún proveedor. No hace falta darle ninguna todavía: ese hueco lo va a ocupar OmniRoute. Por ahora simplemente salimos del programa.

Instalación de OmniRoute

npm install -g omniroute
omniroute

El comando omniroute levanta a la vez la API y el panel web en el puerto 20128:

• Panel: http://localhost:20128
• API compatible con OpenAI: http://localhost:20128/v1

Existen también otras formas de despliegue, útiles si se quiere dejar el gateway funcionando de forma permanente:

docker run omniroute                        # contenedor

Además del paquete npm y el contenedor, el proyecto distribuye una aplicación de escritorio (Electron), imágenes para arm64 (funciona en una Raspberry Pi) y es ejecutable en Android bajo Termux. Una opción interesante es dejar OmniRoute corriendo en un VPS o en un servidor casero y apuntar contra él desde todos los equipos de desarrollo.

Instalación de Ponytail

Ponytail no se instala en el sistema, se declara como plugin de OpenCode. Basta con añadir esta entrada al fichero de configuración opencode.json (en el apartado siguiente se muestra el fichero completo con esta y el resto de piezas):

{ "plugin": ["@dietrichgebert/ponytail"] }

OpenCode descarga el paquete desde npm la primera vez que arranca con esa configuración. Si se prefiere trabajar sobre una copia local del repositorio, para poder modificar las reglas, se clona y se apunta al fichero del plugin:

git clone https://github.com/DietrichGebert/ponytail.git ~/ponytail

{ "plugin": ["/home/usuario/ponytail/.opencode/plugins/ponytail.mjs"] }

Las rutas relativas (del tipo ./.opencode/plugins/ponytail.mjs) se resuelven respecto al opencode.json que las declara, de modo que para compartir un mismo checkout entre varios proyectos hay que usar la ruta absoluta, como en el ejemplo.

Sin plugin también funciona

El repositorio incluye las reglas en formato AGENTS.md y en los formatos de rules de Cursor, Devin, Cline, Kiro, Copilot, etc. Copiando ese fichero al proyecto se obtiene el comportamiento siempre activo en prácticamente cualquier agente. Lo que añade el plugin de OpenCode son los comandos /ponytail y los niveles de intensidad.

Configuración conjunta

La integración consiste en que OpenCode deje de hablar con los proveedores y hable únicamente con OmniRoute, y en que Ponytail se inyecte en cada turno de la conversación. Son cinco pasos.

1. Conectar proveedores en OmniRoute

Con omniroute en marcha, abrimos http://localhost:20128 y vamos a la sección Providers (recomiendo configurar el interfaz en idioma English ya que si no aparecen numerosas cadenas precedidas de la partícula __MISSING__; también utilizar el campo de búsqueda, ya que el número de grupos de configuración de OmniRoute es enorme). Ahí aparece el catálogo con un indicador de cuáles tienen capa gratuita. Conviene conectar varios, ya que el valor del sistema está justamente en la redundancia: cuando uno agota su cuota, el resto siguen disponibles. Los proveedores sin necesidad de clave (No Auth) están conectados por defecto.

El catálogo está clasificado por categorías, y la categoría marca el procedimiento de conexión:

Categoría	Cómo se conecta
No Auth	Están activos desde el primer arranque. Aunque desactivaremos algunos como luego veremos.
Free Tier	Capa gratuita que sí requiere darse de alta en el proveedor y pegar una clave de API.
OAuth	Botón de inicio de sesión para proveedores en los que ya tengamos cuenta: OmniRoute abre el flujo del proveedor y guarda el token resultante.
API Key	Proveedores de pago (algunos con crédito inicial de regalo); se pega la clave.
Local	Modelos que corren en la propia máquina (Ollama, LM Studio, vLLM…); se indica la URL local.

El filtro de la parte superior de la pantalla permite quedarse sólo con las que interesan, y el buscador acepta el nombre o el identificador del proveedor.

Proveedores sin autenticación

En general la elección y configuración de los proveedores es la parte más complicada, farragosa y que más tiempo consume de todo el proceso descrito en este artículo.

No solo eso, algunos de los proveedores activados por defecto como los de la categoría "No Auth", pueden provocar problemas. Durante las primeras sesiones de uso de OpenCode observé que la mayoría de las peticiones obtenían una respuesta vacía. Tras investigar encontré que el problema era la intervención de proveedor "Augment (Auggie CLI)" que por tanto recomiendo desactivar.

Además mirando los logs de la consola de OmniRoute (Monitoring > Logs), encontré que los proveedores "Chipotle Pepper AI (Free)" y "DuckDuckGo AI Chat" fallaban siempre, por lo que aunque no introducen respuestas incorrectas como "Augment (Auggie CLI)", retrasan el recorrido de la cascada de proveedores, por lo que recomiendo desactivarlos también. El proveedor "Veo AI Free" lo desactivaremos, dado que sólo ofrece modelos de vídeo que no nos van a servir para codificar.

Proveedores con clave de API gratuita

El procedimiento es siempre el mismo, cambiando únicamente el sitio del que se obtiene la clave:

1. Darse de alta en el proveedor y generar una clave de API en su panel (el enlace suele estar en la propia ficha del proveedor en OmniRoute).
2. En OmniRoute, Providers → buscar el proveedor → botón de conectar/configurar.
3. Pegar la clave en el formulario y guardar.
4. Pulsar el botón de Test de la tarjeta del proveedor. Si responde correctamente, sus modelos pasan a formar parte del catálogo del gateway y entran automáticamente en el pool del modelo auto.

Los proveedores de esta categoría son los que más nos van a permitir aprovechar las ventajas de OmniRoute. Son numerosos, pero como se comentaba en el apartado anterior, requiere bastante trabajo configurarlos (obtención de API Keys de distintos proveedores) y mantenerse al día de cuáles cambian en operativa o son más o menos recomendables en un momento dado.

Algunos documentos que seguir para mantener en buena forma la lista de proveedores gratuitos son los siguientes:

• Providers Guide - Best Free Providers
• FREE TIERS GUIDE
• FREE TIERS

Algunos de los proveedores de este tipo que me parecen recomendables en el momento de escribir este artículo son:

• Gemini (Google AI Studio)
• Groq
• Mistral
• Cloudflare Workers AI: Tras introducir la API Key, se produce el intento de conexión con los modelos que fallará indicando que hace falta un "Account ID" además. El "Account ID" es el hash que aparece a continuación de la URL https://dash.cloudflare.com una vez creada e iniciada la sesión. Introduciremos ese hash en el campo "Account ID" de los ajustes del provider.
• Pollinations AI: Aunque en el cuadro de conexión se indica que la API Key es opcional, es mejor crear una.

Proveedores OAuth

Con estos no hay clave que copiar: se pulsa el botón de conexión de la tarjeta, se abre el flujo de inicio de sesión del proveedor en el navegador, y al terminar OmniRoute guarda las credenciales cifradas en su base de datos local. Es el caso de las cuentas de herramientas que ya se estén usando (Copilot, Cursor, Kilo Code, Qoder, etc.).

Revisa los términos de servicio

Varios de estos proveedores son en realidad servicios pensados para consumirse desde su propio cliente, y algunos prohíben expresamente en sus condiciones el uso a través de proxies o clientes de terceros. La ficha del proveedor en OmniRoute lo advierte cuando es el caso. Conviene leer esos avisos antes de conectar una cuenta que interese conservar.

Depurar el pool para uso agéntico

Hay una cuestión que no aparece en la documentación de OmniRoute y que, en mi experiencia, ha resultado fundamental para que el montaje resulte operativo. Se trata de que no todos los proveedores del catálogo sirven para alimentar a un agente.

La razón es que un agente como OpenCode no se limita a pedir texto: envía en cada petición la lista de herramientas de las que dispone (leer ficheros, ejecutar comandos, buscar en el repositorio…) y espera que el modelo responda con llamadas a esas herramientas. Los proveedores que son la API oficial de un modelo devuelven esas llamadas al cliente, que es lo correcto. Pero el catálogo incluye también dos tipos de entradas que no se comportan así:

• Proxies de un cliente web (los que se conectan con la cookie de sesión de un chat, en lugar de con una clave de API). El servicio del otro lado tiene su propio motor de herramientas e intenta ejecutarlas él, en su entorno, en lugar de devolverlas.
• Front-ends de agentes (servicios pensados para consumirse desde su propia herramienta de línea de comandos). Traen su propio catálogo de herramientas y no encajan como motor de otro agente.

El síntoma es desconcertante, porque el agente no da ningún error: simplemente devuelve una respuesta vacía, o un texto en el que el modelo explica que no ha podido explorar el repositorio y nos pide, por ejemplo, que le peguemos nosotros el contenido de los ficheros.

Un test de admisión

La forma fiable de decidir si un proveedor entra o no en el pool es preguntárselo al gateway: enviar una petición con una herramienta y comprobar si el modelo la invoca. La respuesta debe contener un bloque tool_calls con el nombre de la herramienta y sus argumentos; si en su lugar llega prosa, ese proveedor no sirve.

No basta con lanzar una petición contra auto/coding y dar por bueno el pool. El enrutado de auto tiende a pegarse al último proveedor que funcionó y no garantiza que todos los candidatos reciban tráfico. Hay que probar cada proveedor por separado.

El comportamiento problemático que queremos detectar (proxies que ejecutan las herramientas ellos mismos, front-ends con su propio catálogo) es una propiedad del proveedor, no del modelo individual: un proxy o pasa las tool_calls al cliente o no las pasa, independientemente del modelo que tenga detrás. Por eso basta con probar un modelo representativo por proveedor, identificable por el prefijo antes de la barra (groq/, mistral/, cf/...), en lugar de los cientos de modelos del catálogo. En realidad probaremos los 5 primeros modelos de cada proveedor por si alguno falla por alguna razón específica. El filtro de jq excluye sólo los modelos virtuales auto/*:

API="http://localhost:20128/v1"
KEY="sk-tu-clave-omniroute"

# Lista de proveedores (excluyendo auto/*)
providers=$(curl -s "$API/models" -H "Authorization: Bearer $KEY" \
  | jq -r '[.data[].id | select(startswith("auto/") | not)]
           | group_by(split("/")[0]) | map(.[0]) | .[]' \
  | cut -d/ -f1 | sort -u)

for prov in $providers; do
  # Hasta 5 modelos de este proveedor
  prov_models=$(curl -s "$API/models" -H "Authorization: Bearer $KEY" \
    | jq -r --arg p "$prov" '[.data[].id | select(startswith($p+"/"))][:5][]')
  status=""
  tested=""
  for model in $prov_models; do
    tested="$model"
    resp=$(curl -s -i "$API/chat/completions" \
      -H "Authorization: Bearer $KEY" \
      -H "Content-Type: application/json" \
      -d "{\"model\":\"$model\",\"stream\":false,\"messages\":[{\"role\":\"user\",\"content\":\"Lee el fichero /etc/hostname\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"read\",\"description\":\"Lee un fichero\",\"parameters\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},\"required\":[\"path\"]}}}]}")
    http_code=$(printf '%s' "$resp" | head -1 | grep -o '[0-9][0-9][0-9]')
    body=$(printf '%s' "$resp" | sed -n '/^\r\?$/,$p' | tail -n +2)
    if [ "$http_code" = "200" ]; then
      if printf '%s' "$body" | jq -e '.choices[0].message.tool_calls[0].function.name' >/dev/null 2>&1; then
        status="OK"
      else
        status="FALLA (sin tool_calls)"
      fi
      break
    elif [ "$http_code" = "401" ] || [ "$http_code" = "403" ]; then
      status="FALLA (auth $http_code)"
      break
    else
      continue  # 404, 400... modelo no disponible, probar el siguiente
    fi
  done
  [ -z "$status" ] && status="FALLA (sin modelos válidos)"
  printf '%-24s %-45s %s\n' "$status" "$prov" "$tested"
done

Requiere jq. El script distingue tres causas de fallo:

• FALLA (sin tool_calls): el proveedor respondió con un 200 pero devolvió prosa en lugar de una llamada a la herramienta. Es el problema que venimos buscando: proxy que ejecuta las tools él mismo o front-end con su propio catálogo. => Desconectar.
• FALLA (auth 401/403): la clave del proveedor está caducada, mal configurada o sin cuota. No es un problema de tools, sino de configuración. => Hay que arreglar la conexión en Providers (o desconectarla si ya no tiene remedio).
• FALLA (sin modelos válidos): todos los modelos probados devolvieron 404 o 400. El proveedor está caído o su catálogo ha cambiado. => Revisar en Providers.

En la salida, la columna de la derecha muestra el modelo con el que se obtuvo el resultado. Es un trabajo que se hace una vez, y que hay que repetir sólo al conectar un proveedor nuevo.

Dos síntomas que reconocer en los logs

En Monitoring > Logs hay dos patrones que delatan a un proveedor que conviene retirar:

• 200 con TO: 0 en unos pocos milisegundos: el proveedor ha devuelto una respuesta vacía con estado de éxito. Una inferencia real nunca tarda 15 ms.
• Respuestas lentas cuyo contenido es texto donde debería haber tool_calls, a menudo con mensajes de error del propio servicio remoto explicando que las herramientas no existen.

El fallback no salta con los fallos disfrazados de éxito

Conviene entender bien el límite del sistema. La cascada de reintentos de OmniRoute funciona con los fallos explícitos: un 429 por cuota, un 502 o un timeout hacen que la petición se reintente contra el siguiente proveedor, y eso se aprecia perfectamente en el registro. Pero los dos casos anteriores llegan al gateway como respuestas correctas: un 200 con un cuerpo vacío es, para un router, una respuesta válida. Ningún gateway puede arbitrar eso sin inspeccionar semánticamente el contenido de cada respuesta.

De ahí que la curación del pool sea responsabilidad nuestra, y que sea un paso que conviene no saltarse. Dicho de otro modo: el enrutado automático es tan bueno como el peor proveedor aparentemente sano del pool.

2. Crear una clave de API de OmniRoute

En el panel, sección API Manager → Create API Key. Le damos un nombre descriptivo (por ejemplo opencode) y copiamos la clave generada, con formato sk-xxxxxxxx-xxxxxxxx.

Esta clave es local: es la que usarán nuestros clientes (OpenCode en este caso) para autenticarse contra OmniRoute, y no tiene nada que ver con las claves de los proveedores, que quedan custodiadas por OmniRoute.

Podemos verificar que el gateway responde y ver qué modelos ofrece:

curl http://localhost:20128/v1/models -H "Authorization: Bearer sk-tu-clave-omniroute"

3. Declarar OmniRoute como proveedor en OpenCode

OpenCode admite cualquier proveedor compatible con OpenAI declarándolo en su fichero de configuración. Para que la configuración aplique a todos los proyectos, la escribimos en ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@dietrichgebert/ponytail"],
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1",
        "apiKey": "sk-tu-clave-omniroute"
      },
      "models": {
        "auto": { "name": "Auto (equilibrado)" },
        "auto/coding": { "name": "Auto (calidad para código)" },
        "auto/cheap": { "name": "Auto (menor coste)" },
        "auto/fast": { "name": "Auto (menor latencia)" },
        "auto/offline": { "name": "Auto (máxima cuota disponible)" }
      }
    }
  },
  "model": "omniroute/auto/coding"
}

Los puntos importantes de esta configuración:

• npm: el adaptador @ai-sdk/openai-compatible es el que se usa con endpoints /v1/chat/completions, que es el caso de OmniRoute.
• options.baseURL: el endpoint del gateway. Si OmniRoute está en otra máquina, aquí va su IP o dominio.
• options.apiKey: la clave de API que creamos en OmniRoute.
• models: no hace falta enumerar modelos concretos de proveedores; basta con declarar los modelos virtuales auto, que son los que activan el enrutado inteligente y el fallback. Si se quiere fijar un modelo concreto, se puede añadir con el identificador que devuelve /v1/models, la consulta del punto anterior.
• model: modelo por defecto al arrancar. auto/coding es una buena elección para desarrollo; auto/offline resulta útil cuando lo prioritario es no quedarse sin cuota.
• plugin: la lista de plugins de OpenCode, donde entra Ponytail.

Clave fuera del fichero de configuración

Si el fichero de configuración se va a versionar (por ejemplo en un repositorio de dotfiles), es preferible no escribir la clave en él. OpenCode permite almacenar credenciales con el comando /connect (opción Other, id omniroute), en cuyo caso se puede omitir options.apiKey del JSON.

También es posible ubicar el fichero como opencode.json en la raíz de un proyecto concreto, en cuyo caso su configuración se combina con la global. Esto resulta práctico para forzar un modelo distinto en un proyecto determinado.

4. Ajustar el nivel de Ponytail

Ponytail no necesita fichero de configuración: funciona nada más declararlo como plugin. Lo único que conviene decidir es el nivel de intensidad, que se cambia en caliente desde la TUI:

/ponytail            → informa del nivel actual
/ponytail lite       → recorte suave
/ponytail full       → nivel por defecto
/ponytail ultra      → recorte agresivo
/ponytail off        → desactivado para esta sesión

El nivel por defecto es full. Para fijar otro en todas las sesiones nuevas se usa la variable de entorno PONYTAIL_DEFAULT_MODE o el campo defaultMode de ~/.config/ponytail/config.json:

export PONYTAIL_DEFAULT_MODE="full"

Mientras está activo, el conjunto de reglas se inyecta también en los subagentes que lance el agente principal. Si interesa excluir a alguno (por ejemplo los subagentes de búsqueda, que no escriben código), se puede acotar con una expresión regular contra el tipo de subagente definida en la siguiente variable de entorno:

export PONYTAIL_SUBAGENT_MATCHER="build|code"

5. Verificar la integración

Arrancamos el agente y comprobamos que aparece el proveedor:

opencode

Dentro de la TUI, el comando /models debe mostrar las entradas de OmniRoute.

Desde un directorio que contenga un repositorio o un proyecto, ejecutamos una prueba rápida en modo CLI no interactivo:

opencode run "Resume en tres líneas qué hace este repositorio" --model omniroute/auto/coding

Mientras se ejecuta, en el panel de OmniRoute puede verse en tiempo real qué proveedor ha atendido la petición (Monitoring > Logs), cuántos tokens se han consumido y cuántos ha ahorrado la compresión. Si un proveedor falla, en el registro se aprecia el salto automático al siguiente.

Para comprobar que Ponytail está cargado basta con ejecutar /ponytail en la TUI, que responde con el nivel activo, o /ponytail-help, que lista sus comandos.

Aparente ERROR de arranque de Ponytail

Si se arranca OpenCode con --print-logs puede aparecer esta línea al cargar la configuración:

ERROR message="failed to load plugin" path=@dietrichgebert/ponytail error="path must be a string or a file descriptor"

Es engañosa: OpenCode intenta cargar el plugin por dos rutas y una de ellas falla, pero la otra lo carga correctamente. La prueba de que Ponytail está operativo es que /ponytail responda con el nivel activo. Hay que tener en cuenta además que el nivel se persiste entre sesiones (en ~/.config/opencode/.ponytail-active): un /ponytail off de una prueba anterior deja el plugin cargado pero desactivado. Ante la duda: /ponytail full y preguntar al agente qué dice su system prompt sobre PONYTAIL.

Variables de entorno para el resto de herramientas

Exportando estas variables en el .bashrc o .zshrc, cualquier otra herramienta que respete la convención de OpenAI usará también el gateway sin configuración adicional:

export OPENAI_BASE_URL="http://localhost:20128/v1"
export OPENAI_API_KEY="sk-tu-clave-omniroute"

Tipos de proyectos y operativa

Una vez montado el entorno, la operativa es esencialmente la misma con independencia del lenguaje, del tamaño del proyecto o la naturaleza de la tarea. Lo que cambia entre unos casos y otros no es el procedimiento, sino el modelo que conviene seleccionar, el nivel de recorte que interesa y la cantidad de contexto que hay que preparar. Por eso describimos primero el flujo común y después los ajustes por tipo de proyecto.

Operativa común

1. Situarse en el repositorio y arrancar el agente:

   cd mi-proyecto
   opencode
   

2. Generar el fichero de contexto la primera vez, con el comando /init dentro de la TUI. OpenCode explora el repositorio y escribe un AGENTS.md con la descripción del proyecto, los comandos de compilación y test y las convenciones detectadas. Merece la pena revisarlo y completarlo a mano: es el documento que más influye en la calidad de los resultados posteriores, y conviene versionarlo con el proyecto.

3. Planificar antes de ejecutar. Para cualquier cambio que no sea trivial, pedir primero un plan en lugar de la implementación directa. OpenCode dispone de un modo de planificación que no escribe en disco, y revisar el plan cuesta mucho menos que revisar un diff equivocado de 400 líneas.

4. Iterar en pasos pequeños, validando con las herramientas del propio proyecto (compilador, linter, tests) tras cada paso. El agente puede ejecutar esos comandos por sí mismo si están documentados en AGENTS.md.

5. Pasar la revisión de Ponytail antes de dar la tarea por buena, con /ponytail-review. Analiza el diff actual buscando sobre-ingeniería y devuelve una lista de cosas a borrar. Es el paso que más rápido amortiza el tiempo invertido.

6. Revisar el diff y confirmar con el control de versiones. Conviene trabajar siempre sobre una rama y hacer commits pequeños: es la red de seguridad natural cuando quien escribe el código es un agente.

7. Limpiar el contexto entre tareas con /new. Arrastrar el contexto de una tarea terminada empeora los resultados y dispara el consumo de tokens. En el apartado siguiente se detalla la gestión de sesiones.

8. Vigilar el panel de OmniRoute de vez en cuando para ver qué proveedores se están usando, cuáles se han agotado y si el ahorro por compresión es el esperado.

Gestión de sesiones en OpenCode

Al empezar a trabajar con OpenCode sorprende comprobar que, por mucho que se salga de la TUI con Ctrl-d o con /exit, las sesiones siguen apareciendo en el listado. No es un problema de cierre incompleto ni un proceso que se quede colgado: es que una sesión no es un proceso, es una conversación persistida. Salir de la TUI termina la interfaz, pero el historial de la conversación (mensajes, herramientas ejecutadas, ficheros tocados, consumo de tokens) se guarda en la base de datos local de OpenCode para poder retomarlo después. Y como cada invocación de opencode sin argumentos abre una sesión nueva, en un par de días de uso el listado tiene decenas de entradas.

Dicho de otra forma: "cerrar" no significa "borrar". Lo que hay que adquirir es la costumbre de reutilizar y de podar.

Retomar en lugar de crear

Lo primero es dejar de arrancar siempre en blanco. Estas son las tres formas de continuar un trabajo previo:

opencode --continue                  # retoma la última sesión del proyecto actual (-c)
opencode --session <sessionID>       # retoma una sesión concreta (-s)
opencode --session <sessionID> --fork # la bifurca en una copia, dejando la original intacta

Y desde dentro de la TUI, el comando /sessions (alias /resume y /continue, atajo Ctrl-x l) abre el selector para saltar de una sesión a otra sin salir del programa.

La opción --fork es especialmente útil cuando una conversación ha llegado a un punto interesante y se quiere probar dos caminos distintos: se bifurca y cada rama sigue por su lado, igual que con git branch.

Cerrar bien cada tarea

Dentro de la TUI hay dos comandos que marcan el final de una tarea:

• /new (alias /clear, atajo Ctrl-x n): abre una sesión nueva y limpia. Es lo que hay que usar al cambiar de tarea, en lugar de seguir escribiendo en la conversación anterior.
• /compact (alias /summarize, atajo Ctrl-x c): resume la conversación actual para liberar ventana de contexto sin perder el hilo. Es la alternativa cuando se quiere continuar con la misma tarea pero el contexto se ha vuelto pesado.

Si de una sesión interesa conservar el resultado, /export vuelca la conversación a Markdown y la abre en el editor, y opencode export <sessionID> hace lo propio en JSON desde la línea de comandos.

Inventariar y podar

Desde fuera de la TUI se gestiona el inventario completo:

opencode session list                # listado de sesiones
opencode session list -n 20          # limitar el número de entradas
opencode session list --format json  # salida procesable por script
opencode session delete <sessionID>  # eliminar una sesión

Y para ver el coste de lo acumulado, que en este montaje es lo que determina cuánta cuota gratuita se está quemando:

opencode stats                       # consumo de tokens y coste
opencode stats --days 7 --models     # últimos 7 días, desglosado por modelo
opencode stats --project             # sólo el proyecto actual

Flujo de trabajo

Reuniendo lo anterior, la rutina que mantiene el listado bajo control es:

1. Una sesión por tarea, no por jornada ni por proyecto. La unidad natural es lo que acaba en un commit.
2. Retomar con -c cuando se vuelve a una tarea a medias, en vez de arrancar opencode a secas y volver a explicar el contexto (que además se paga en tokens).
3. /new al cambiar de tarea y /compact si la tarea se alarga pero sigue siendo la misma.
4. Exportar lo que merezca la pena antes de dar por cerrada una sesión con conclusiones valiosas.
5. Poda periódica, por ejemplo semanal, revisando opencode session list y borrando con opencode session delete todo lo que ya esté commiteado y no aporte nada.
6. Revisar opencode stats en esa misma poda, para tener la foto del consumo junto a la del panel de OmniRoute.

Las sesiones van por proyecto

OpenCode asocia las sesiones al directorio de trabajo desde el que se lanzó, así que --continue o -c retoma la última sesión de ese proyecto, no la última en términos absolutos. Es un detalle que ayuda: trabajar siempre desde la raíz del repositorio mantiene los listados ordenados por proyecto de forma natural.

Comandos de Ponytail

Más allá del nivel de intensidad, el skill aporta un puñado de comandos que encajan en distintos momentos del flujo anterior:

Comando	Para qué sirve
/ponytail [lite \| full \| ultra \| off]	Ajusta la intensidad o la desactiva. Sin argumento informa del nivel actual.
/ponytail-review	Revisa el diff actual en busca de sobre-ingeniería y devuelve una lista de borrado.
/ponytail-audit	Lo mismo, pero sobre todo el repositorio en lugar de sobre el diff.
/ponytail-debt	Recopila en un registro los atajos marcados con ponytail: que se hayan ido aplazando.
/ponytail-gain	Muestra el marcador de impacto medido (menos código, menos coste, más velocidad).
/ponytail-help	Referencia rápida de los comandos anteriores.

Cuando el agente decide no construir algo, deja un comentario del tipo ponytail: browser has one explicando el peldaño de la escalera en el que se detuvo. Esos comentarios son los que después recoge /ponytail-debt, de forma que las decisiones de "esto ya se hará si hace falta" quedan registradas en lugar de perderse.

Ajustes según el tipo de proyecto

Lo único que varía de forma apreciable entre escenarios es la elección de modelo y la preparación del contexto:

• Proyectos nuevos desde cero (greenfield). Hay poco contexto que cargar y mucho código que generar. Es el escenario ideal para las capas gratuitas: auto/cheap o auto/offline dan buen resultado y el consumo de tokens de entrada es bajo. Conviene empezar pidiendo el andamiaje del proyecto y el fichero de dependencias, y sólo después las funcionalidades. También es donde más se nota Ponytail, porque es donde el agente tiene más libertad para inventar estructura de más.

• Mantenimiento y evolución de código existente. Aquí el cuello de botella es el contexto: el agente necesita leer bastante código antes de tocar nada. Interesa un AGENTS.md detallado, activar la compresión de contexto de OmniRoute y usar auto/coding para las tareas de modificación. Es también el caso donde más se nota el fallback, porque las sesiones son largas. El peldaño "¿ya está en este repositorio?" de Ponytail resulta especialmente valioso, ya que evita el clásico duplicado de un helper que ya existía tres directorios más allá.

• Depuración de errores. El flujo es el mismo, pero funciona mucho mejor si se le proporciona al agente una forma de reproducir el fallo (un test que falle, la traza completa, el comando exacto). Modelos con capacidad de razonamiento explícito dan mejores resultados; en OmniRoute se pueden seleccionar las variantes thinking de los modelos que las ofrezcan. Un nivel lite de Ponytail, o incluso off, puede ser preferible aquí: al depurar interesa entender, no recortar.

• Scripting y automatización. Aquí interesa el modo CLI no interactivo, que permite integrar el agente en scripts, hooks de git o tareas programadas:

  opencode run "Actualiza el CHANGELOG con los commits desde la última etiqueta" \
    --model omniroute/auto/fast
  

• Refactorizaciones amplias y repetitivas. Trocear el trabajo en tareas independientes y lanzarlas por separado, en lugar de pedir un cambio masivo en una sola sesión. Además de dar mejores resultados, evita agotar la ventana de contexto y la cuota de un proveedor de una sentada. Si lo que se busca es precisamente adelgazar código heredado, /ponytail-audit sobre el repositorio completo y /ponytail ultra son el punto de partida natural.

• Proyectos con código sensible. Si no se puede enviar el código a terceros, la misma configuración sirve conectando en OmniRoute un proveedor local (Ollama o LM Studio en la propia máquina) en lugar de los servicios gratuitos. Cambia el proveedor conectado en el panel; ni OpenCode ni el flujo de trabajo se tocan.

Conclusión

La combinación de OpenCode, OmniRoute y Ponytail proporciona un entorno de desarrollo agéntico completo con coste de entrada nulo y sin las interrupciones por cuota agotada que caracterizan a las alternativas comerciales. Cada pieza ataca un frente distinto: el agente aporta las capacidades, el gateway la cuota y la independencia de proveedor, y el skill la disciplina para que el código generado sea el mínimo necesario. Y las tres se declaran en un único fichero de configuración de unas veinte líneas.

El precio a pagar es una configuración inicial algo más laboriosa que la de un producto cerrado y la necesidad de revisar de vez en cuando qué proveedores gratuitos siguen operativos. A cambio se obtiene algo que las suscripciones no dan: independencia respecto al proveedor, visibilidad completa de lo que consume el agente y menos código del que arrepentirse.