Modèles gratuits pour OpenCode via FreeLLMAPI

OpenCode est un agent de programmation ouvert qui fonctionne dans le terminal : lit les fichiers de projet, édite le code, exécute des commandes et des tests, recherche dans le référentiel et fonctionne avec git. Il n’est pas lié à un seul fournisseur de modèles, donc presque tous les services compatibles OpenAI peuvent y être connectés.

FreeLLMAPI est un routeur ouvert auto-hébergé qui collecte les plans gratuits de dizaines de fournisseurs d’IA sous une seule adresse /v1 compatible OpenAI. Au lieu de trente clés, trente limites et trente endroits où une requête peut échouer, vous disposez d’une passerelle locale et d’une clé unifiée. Le routeur sélectionne lui-même un modèle disponible, passe au suivant lorsque l’erreur 429 ou 5xx se produit et s’assure que les demandes ne dépassent pas les quotas des tarifs gratuits.

Dans cet article, je décrirai l’installation de FreeLLMAPI, l’ajout de fournisseurs et la connexion de la passerelle à OpenCode.

Ce dont vous avez besoin

Pour travailler, vous avez besoin de quatre choses :

• OpenCode installé. Si l’agent n’est pas encore installé, j’ai discuté de la procédure d’installation dans une note séparée sur OpenCode et DeepSeek.
• FreeLLMAPI en cours d’exécution. Le moyen le plus simple consiste à installer une application de bureau ou un conteneur Docker.
• Node.js 20.18 ou version ultérieure. Ceci est nécessaire pour le générateur CLI qui configure OpenCode. OpenCode lui-même peut être installé sans Node.
• Clés d’au moins un fournisseur. Les forfaits gratuits de Google AI Studio, Groq, Cerebras, Mistral, OpenRouter, NVIDIA, HuggingFace et d’autres services du catalogue conviennent.

Installation de FreeLLMAPI

Le projet comporte plusieurs chemins d’installation. Choisissez celui qui convient le mieux à votre système.

Application de bureau

L’option la plus simple pour Windows et macOS est le programme d’installation prêt à l’emploi de la page des versions. Sous Windows, il s’agit de .exe, sur macOS, il s’agit de .dmg pour Apple Silicon ou Intel. L’application réside dans le bac et élève localement le routeur ainsi que le panneau de commande.

Aucun mot de passe n’est nécessaire pour la version de bureau : le panneau se connecte tout seul via un compte local masqué. Les seules informations d’identification dont vous aurez besoin sont la clé unifiée de la fenêtre contextuelle de la barre d’état système ou de l’en-tête de la page Clés.

Les données de l’application se trouvent dans un répertoire :

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

Docker

Si Docker est déjà installé, le serveur est lancé avec une seule commande. Le script crée le répertoire ~/freellmapi, génère une clé de chiffrement, télécharge l’image et démarre le conteneur :

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

La réexécution du script est sécurisée : le fichier .env et la clé de chiffrement sont enregistrés et le conteneur est mis à jour vers la dernière version. Sous Windows, cette méthode fonctionne dans WSL ou dans n’importe quel environnement bash.

Après le lancement, le panneau s’ouvre à :

http://localhost:3001

Pour l’installation du serveur, vous devez créer un compte avec un email et un mot de passe. En cas d’oubli du mot de passe, le code de réinitialisation est imprimé dans le journal du conteneur :

docker compose logs -f freellmapi

Docker Compose

Si vous souhaitez conserver la configuration dans git et gérer le lancement manuellement, Compose standard fera l’affaire. Sous macOS et 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

Sous 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 clé ENCRYPTION_KEY est obligatoire : elle permet de chiffrer les clés du fournisseur dans la base de données SQLite. Vous ne pouvez pas le modifier à la volée – les anciens secrets ne seront plus déchiffrés. Pour la rotation, le projet dispose d’une commande séparée rotate-encryption-key.

Exécuter à partir des sources

Pour le développement ou le débogage, vous pouvez exécuter le projet via 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

Dans ce mode, l’API et le panneau sont activés sur le port 3001 et l’interface Vite est activée sur le port 5173.

Premier lancement et clés du fournisseur

Ouvrez le panneau, accédez à la page Clés et ajoutez les clés des services que nous utilisons. Pour chaque fournisseur, l’interface propose un lien vers l’inscription et une indication où obtenir la clé. Il suffit de commencer par un ou deux : par exemple, Google AI Studio et Groq.

Une fois ajoutée, la clé subit un bilan de santé. Si le fournisseur a répondu par une erreur, la clé restera dans la liste, mais sera marquée comme non saine – elle peut être vérifiée à nouveau ou supprimée.

Ensuite, vous devez accéder à la page Modèles et voir quels modèles sont disponibles. Là, vous pouvez également configurer la stratégie de routage et l’ordre de la Chaîne de secours – la chaîne le long de laquelle le routeur parcourt en cas d’erreurs et de limites. Le modèle auto signifie que le choix est fait par le routeur lui-même. En plus de cela, des options telles que auto:fast, auto:smart et des profils nommés pour des tâches spécifiques sont disponibles.

Il convient également de vérifier qu’il existe des modèles dans la chaîne prenant en charge les outils. OpenCode utilise activement les appels d’outils, et un modèle sans cette fonctionnalité ne pourra pas lire les fichiers ou exécuter des commandes normalement.

La clé unifiée se trouve là, sur la page Clés ou dans la barre d’état de l’application de bureau. Cela ressemble à une chaîne avec un préfixe :

freellmapi-...

C’est cette clé, et non les clés des fournisseurs individuels, qui est indiquée dans OpenCode.

Connectez-vous à OpenCode

FreeLLMAPI dispose d’un générateur de configuration qui lit lui-même le répertoire modèle de la passerelle en cours d’exécution, crée une copie de sauvegarde de la configuration existante et y ajoute soigneusement le fournisseur.

Tout d’abord, définissons la clé unifiée sur la variable d’environnement. Le générateur le lit au lieu d’un indicateur séparé, de sorte que le secret ne se retrouvera pas dans l’historique des commandes.

Sous macOS et Linux :

export FREELLMAPI_API_KEY=freellmapi-YOUR_KEY

Sous Windows PowerShell :

$env:FREELLMAPI_API_KEY="freellmapi-YOUR_KEY"

Voyons maintenant ce qui sera exactement enregistré :

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

Si diff est satisfaisant, répétez la commande sans le flag :

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

Le générateur écrit la configuration globale OpenCode :

~/.config/opencode/opencode.json

Le fournisseur freellmapi y apparaît avec le package @ai-sdk/openai-compatible, l’adresse de base http://localhost:3001/v1 et une carte des modèles du catalogue live. Le modèle par défaut devient freellmapi/auto.

La clé elle-même ne finit pas dans le fichier : la config contient la substitution {env:FREELLMAPI_API_KEY}. Par conséquent, la variable doit rester définie au démarrage de l’agent :

opencode

Cette méthode est également pratique car le secret ne se retrouve pas dans la configuration et ne se retrouvera pas dans git. Pour les exécutions CI et uniques, c’est plus correct que de stocker la clé dans un fichier.

Réglage manuel

Si vous ne souhaitez pas exécuter le générateur, vous pouvez décrire manuellement le fournisseur dans opencode.json. L’option minimale ressemble à ceci :

{
  "$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 }
        }
      }
    }
  }
}

Le champ modèle au niveau supérieur est important : sans lui, OpenCode peut continuer à utiliser le modèle précédent ou ne rien sélectionner sur une nouvelle installation. Il est préférable de prendre le contexte et les limites de sortie de la réponse de la passerelle, plutôt que de les inventer :

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

Vous pouvez ajouter des identifiants spécifiques à la liste des modèles si vous devez y accéder manuellement. Mais pour le travail quotidien, l’auto suffit : le routeur lui-même sélectionnera un modèle vivant et commutera lorsque la limite sera atteinte.

Comment l’utiliser

Après avoir lancé opencode, la liste des modèles s’ouvre avec une commande familière :

/models

Il aura un fournisseur FreeLLMAPI et un modèle automatique. Ensuite, le travail se déroule comme d’habitude : nous décrivons la tâche, spécifions les fichiers via @, changeons de mode de planification avec la touche Tab, annulons les modifications avec la commande /undo. Pour un nouveau projet, il est utile d’exécuter /init pour que l’agent crée AGENTS.md.

Quelques conseils pratiques :

• Routage. Pour la routine, laissez-le sur automatique. Si vous avez besoin de rapidité, essayez auto:fast, si la qualité est auto:smart ou un modèle puissant spécifique du catalogue.
• Diagnostics Chaque réponse de passerelle contient un en-tête X-Routed-Via avec le nom du fournisseur et le modèle qui a réellement servi la requête. Il montre où le routeur a envoyé la tâche.
• Analytics. Sur la page Analytics, le panneau affiche le volume de demandes, le succès, les retards p50/p95 et la consommation de jetons par fournisseur.
• Continuité du dialogue. Lors du changement de modèle au milieu d’une conversation, la passerelle peut ajouter une courte note sur le transfert de contexte. Activé par la variable FREELLMAPI_CONTEXT_HANDOFF=on_model_switch.

Si OpenCode s’exécute dans un conteneur et que FreeLLMAPI s’exécute sur un hôte, localhost pointera vers le conteneur lui-même. Dans ce cas, vous devez utiliser host.docker.internal ou une autre adresse accessible depuis le conteneur dans la baseURL.

À quoi faire attention

FreeLLMAPI ne remplace pas les modèles payants et n’est pas un service avec un SLA. C’est un moyen de regrouper les forfaits gratuits en une seule passerelle soignée. Il y a donc plusieurs restrictions :

• La qualité fluctue. Les tarifs gratuits prennent fin et, tard dans la soirée, à l’approche de l’épuisement des quotas quotidiens, le routeur peut passer à des modèles plus faibles. Les quotas sont généralement réinitialisés à minuit UTC.
• Les latences sont variables. Différents fournisseurs réagissent différemment et lors du passage à un modèle de sauvegarde, la demande peut prendre sensiblement plus de temps.
• Il n’existe pas de modèles phares. De bons modèles, mais pas haut de gamme, sont disponibles dans les forfaits gratuits. Pour les architectures complexes, cela vaut la peine d’être pris en compte.
• La passerelle doit être en cours d’exécution. Si l’application ou le conteneur est arrêté, OpenCode ne recevra pas de réponse. Le démarrage automatique de l’application dans la barre d’état ou le redémarrage de la stratégie du conteneur résout ce problème.
• Le projet est conçu pour un seul utilisateur. Les clés du fournisseur sont stockées localement et cryptées, mais un panneau partagé pour plusieurs personnes n’est pas le scénario pour cet outil. La clé unifiée et .env doivent être protégés de la même manière qu’un secret ordinaire.

Et encore une nuance : le catalogue de modèles se met à jour tout seul, mais l’installation gratuite reçoit un instantané du catalogue avec un délai d’une trentaine de jours. Le forfait payant Premium accélère la mise à jour, mais il n’est pas nécessaire de se familiariser avec le projet – le routeur lui-même reste gratuit et ouvert.

Liens

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/

Sources

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/