Modelos gratuitos para OpenCode a través de FreeLLMAPI

OpenCode es un agente de programación abierto que funciona en la terminal: lee archivos de proyecto, edita código, ejecuta comandos y pruebas, busca en el repositorio y trabaja con git. No está vinculado a un solo proveedor de modelo, por lo que se puede conectar a él casi cualquier servicio compatible con OpenAI.

FreeLLMAPI es un enrutador abierto y autohospedado que recopila planes gratuitos de docenas de proveedores de IA en una dirección /v1 compatible con OpenAI. En lugar de treinta claves, treinta límites y treinta lugares donde una solicitud puede fallar, tiene una puerta de enlace local y una clave unificada. El propio enrutador selecciona un modelo disponible, cambia al siguiente cuando ocurre el error 429 o 5xx y se asegura de que las solicitudes no excedan las cuotas de tarifas gratuitas.

En esta publicación describiré la instalación de FreeLLMAPI, la adición de proveedores y la conexión de la puerta de enlace a OpenCode.

Lo que necesitas

Para trabajar necesitas cuatro cosas:

• OpenCode instalado. Si el agente aún no está instalado, analicé el procedimiento de instalación en una nota separada sobre OpenCode y DeepSeek.
• FreeLLMAPI en ejecución. La forma más sencilla es instalar una aplicación de escritorio o un contenedor Docker.
• Node.js 20.18 o posterior. Esto es necesario para el generador CLI que configura OpenCode. El propio OpenCode se puede instalar sin Node.
• Claves de al menos un proveedor. Son adecuados los planes gratuitos de Google AI Studio, Groq, Cerebras, Mistral, OpenRouter, NVIDIA, HuggingFace y otros servicios del catálogo.

Instalando FreeLLMAPI

El proyecto tiene varias vías de instalación. Elija el que sea más conveniente para su sistema.

Aplicación de escritorio

La opción más sencilla para Windows y macOS es el instalador listo para usar en la página de lanzamientos. En Windows es .exe, en macOS es .dmg para Apple Silicon o Intel. La aplicación vive en la bandeja y levanta el enrutador junto con el panel de control localmente.

No se necesita contraseña para la versión de escritorio: el panel inicia sesión por sí solo a través de una cuenta local oculta. Las únicas credenciales que necesitará son la clave unificada de la ventana emergente de la bandeja o del encabezado de la página Claves.

Los datos de la aplicación se encuentran en un directorio:

• Windows — %APPDATA%\FreeLLMAPI\
• macOS — ~/Library/Application Support/FreeLLMAPI/
• Linux — ~/.config/FreeLLMAPI/

Docker

Si Docker ya está instalado, el servidor se activa con un comando. El script crea el directorio ~/freellmapi, genera una clave de cifrado, descarga la imagen e inicia el contenedor:

curl -fsSL https://freellmapi.co/install.sh | bash

Ejecutar el script nuevamente es seguro: el archivo .env y la clave de cifrado se guardan y el contenedor se actualiza a la última versión. En Windows, este método funciona en WSL o en cualquier entorno bash.

Después del lanzamiento, el panel se abre en:

http://localhost:3001

Para la instalación del servidor, debe crear una cuenta con un correo electrónico y una contraseña. Si se olvida la contraseña, el código de restablecimiento se imprime en el registro del contenedor:

docker compose logs -f freellmapi

Docker Compose

Si desea mantener la configuración en git y administrar el inicio manualmente, Compose normal será suficiente. En macOS y Linux:

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
ENCRYPTION_KEY="$(openssl rand -hex 32)"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
docker compose up -d

En Windows PowerShell:

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
$Bytes = New-Object Byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($Bytes)
$ENCRYPTION_KEY = -join ($Bytes | ForEach-Object { "{0:x2}" -f $_ })
"ENCRYPTION_KEY=$ENCRYPTION_KEY`nPORT=3001" | Out-File -Encoding utf8 .env
docker compose up -d

La clave ENCRYPTION_KEY es obligatoria: se utiliza para cifrar claves de proveedor en la base de datos SQLite. No puede cambiarlo sobre la marcha: los viejos secretos ya no se descifrarán. Para la rotación, el proyecto tiene un comando independiente para rotar clave de cifrado.

Ejecutando desde la fuente

Para desarrollo o depuración, puede ejecutar el proyecto a través de Node.js:

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install
ENCRYPTION_KEY="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
npm run dev

En este modo, la API y el panel se generan en el puerto 3001 y la interfaz Vite se genera en el 5173.

Primer lanzamiento y claves del proveedor

Abrimos el panel, vamos a la página Claves y agregamos las claves de los servicios que utilizamos. Para cada proveedor, la interfaz tiene un enlace de registro y una pista de dónde obtener la clave. Basta con empezar con uno o dos: por ejemplo, Google AI Studio y Groq.

Una vez agregada, la clave se somete a un control de estado. Si el proveedor respondió con un error, la clave permanecerá en la lista, pero se marcará como en mal estado; se puede verificar nuevamente o eliminar.

A continuación, debes ir a la página Modelos y ver qué modelos están disponibles. Allí también puede configurar la estrategia de enrutamiento y el orden de la Fallback Chain, la cadena por la que pasa el enrutador en caso de errores y límites. El modelo auto significa que la elección la realiza el propio enrutador. Además, están disponibles opciones como auto:fast, auto:smart y perfiles con nombre para tareas específicas.

También vale la pena comprobar que existen modelos en la cadena que admiten herramientas. OpenCode utiliza activamente la llamada a herramientas y un modelo sin esta función no podrá leer archivos ni ejecutar comandos normalmente.

La clave unificada se lleva allí, en la página Claves o en la bandeja de la aplicación de escritorio. Parece una cadena con un prefijo:

freellmapi-...

Es esta clave, y no las claves de proveedores individuales, la que se indica en OpenCode.

Conectarse a OpenCode

FreeLLMAPI tiene un generador de configuración que lee el directorio del modelo desde la puerta de enlace en ejecución, hace una copia de seguridad de la configuración existente y le agrega cuidadosamente el proveedor.

Primero, configuremos la clave unificada para la variable de entorno. El generador lo lee en lugar de una bandera separada, por lo que el secreto no terminará en el historial de comandos.

En macOS y Linux:

export FREELLMAPI_API_KEY=freellmapi-YOUR_KEY

En Windows PowerShell:

$env:FREELLMAPI_API_KEY="freellmapi-YOUR_KEY"

Ahora veamos qué se grabará exactamente:

npx freellmapi setup-opencode --url http://localhost:3001 --dry-run

Si la diferencia es satisfactoria, repita el comando sin la bandera:

npx freellmapi setup-opencode --url http://localhost:3001

El generador escribe la configuración global de OpenCode:

~/.config/opencode/opencode.json

El proveedor freellmapi aparece en él con el paquete @ai-sdk/openai-compatible, la dirección base http://localhost:3001/v1 y un mapa de modelos del catálogo en vivo. El modelo predeterminado pasa a ser freellmapi/auto.

La clave en sí no termina en el archivo: la configuración contiene la sustitución {env:FREELLMAPI_API_KEY}. Por lo tanto, la variable debe permanecer configurada cuando se inicia el agente:

opencode

Este método también es conveniente porque el secreto no termina en la configuración y no terminará en git. Para CI y ejecuciones únicas, esto es más correcto que almacenar la clave en un archivo.

Configuración manual

Si no desea ejecutar el generador, puede describir manualmente el proveedor en opencode.json. La opción mínima se ve así:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "freellmapi/auto",
  "provider": {
    "freellmapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "FreeLLMAPI",
      "options": {
        "baseURL": "http://localhost:3001/v1",
        "apiKey": "{env:FREELLMAPI_API_KEY}"
      },
      "models": {
        "auto": {
          "name": "FreeLLMAPI Auto Router",
          "limit": { "context": 1048576, "output": 65536 }
        }
      }
    }
  }
}

El campo modelo en el nivel superior es importante: sin él, OpenCode puede continuar usando el modelo anterior o no seleccionar nada en una instalación nueva. Es mejor tomar el contexto y los límites de salida de la respuesta de la puerta de enlace, en lugar de inventarlos:

curl http://localhost:3001/v1/models

Puede agregar identificadores específicos a la lista de modelos si necesita cambiarlos manualmente. Pero para el trabajo diario, el modo automático es suficiente: el propio enrutador seleccionará un modelo en vivo y cambiará cuando se alcance el límite.

Cómo usarlo

Después de iniciar el código abierto, la lista de modelos se abre con un comando familiar:

/models

Tendrá un proveedor FreeLLMAPI y un modelo automático. Luego, el trabajo continúa como de costumbre: describimos la tarea, especificamos archivos mediante @, cambiamos el modo de planificación con la tecla Tab, revertimos las ediciones con el comando /undo. Para un proyecto nuevo, es útil ejecutar /init para que el agente cree AGENTS.md.

Un par de consejos prácticos:

• Enrutamiento. Para rutina, déjelo en automático. Si necesitas velocidad, prueba auto:fast, si la calidad es auto:smart o un modelo potente específico del catálogo.
• Diagnóstico Cada respuesta de puerta de enlace contiene un encabezado X-Routed-Via con el nombre del proveedor y el modelo que realmente atendió la solicitud. Muestra dónde el enrutador envió la tarea.
• Análisis. En la página Análisis, el panel muestra el volumen de solicitudes, el éxito, los retrasos p50/p95 y el consumo de tokens por proveedor.
• Continuidad del diálogo. Al cambiar de modelo en medio de una conversación, la puerta de enlace puede agregar una breve nota sobre la transferencia de contexto. Habilitado por la variable FREELLMAPI_CONTEXT_HANDOFF=on_model_switch.

Si OpenCode se ejecuta en un contenedor y FreeLLMAPI se ejecuta en un host, localhost apuntará al contenedor mismo. En este caso, debe utilizar host.docker.internal u otra dirección accesible desde el contenedor en la URL base.

A qué prestar atención

FreeLLMAPI no reemplaza los modelos pagos ni es un servicio con un SLA. Es una forma de agrupar planes gratuitos en una única puerta de enlace. De ahí que existan varias restricciones:

• La calidad fluctúa. Las tarifas gratuitas terminan y, a última hora de la noche, cuando se acerca el agotamiento de las cuotas diarias, el enrutador puede cambiar a modelos más débiles. Las cuotas suelen restablecerse a la medianoche UTC.
• Las latencias son variables. Los distintos proveedores responden de forma diferente y, al cambiar a un modelo de copia de seguridad, la solicitud puede tardar considerablemente más.
• No hay modelos emblemáticos. Hay modelos buenos, pero no de gama alta, disponibles en planes gratuitos. Para arquitecturas complejas vale la pena considerar esto.
• La puerta de enlace debe estar ejecutándose. Si la aplicación o el contenedor se detiene, OpenCode no recibirá una respuesta. Iniciar automáticamente la aplicación en la bandeja o reiniciar la política del contenedor resuelve este problema.
• El proyecto está diseñado para un usuario. Las claves del proveedor se almacenan localmente y están cifradas, pero un panel compartido para varias personas no es el escenario para esta herramienta. La clave unificada y el .env deben protegerse de la misma manera que un secreto normal.

Y un matiz más: el catálogo de modelos se actualiza solo, pero la instalación gratuita recibe una instantánea del catálogo con un retraso de unos treinta días. El plan pago Premium acelera la actualización, pero no es necesario familiarizarse con el proyecto: el enrutador permanece gratuito y abierto.

Enlaces

https://github.com/tashfeenahmed/freellmapi
https://freellmapi.co/
https://freellmapi.co/models
https://github.com/tashfeenahmed/freellmapi/releases/latest
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/01-agent-clients.md
https://github.com/tashfeenahmed/freellmapi/blob/main/cli/README.md
https://opencode.ai/
https://opencode.ai/docs/
https://opencode.ai/docs/providers/

Fuentes

https://github.com/tashfeenahmed/freellmapi
https://github.com/tashfeenahmed/freellmapi/blob/main/README.ru.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/01-agent-clients.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/02-supported-agents.md
https://github.com/tashfeenahmed/freellmapi/blob/main/cli/README.md
https://opencode.ai/docs/providers/