Kostenlose Modelle für OpenCode über FreeLLMAPI

OpenCode ist ein offener Programmieragent, der im Terminal arbeitet: Projektdateien liest, Code bearbeitet, Befehle und Tests ausführt, das Repository durchsucht und mit Git arbeitet. Es ist nicht an einen Modellanbieter gebunden, sodass nahezu jeder OpenAI-kompatible Dienst damit verbunden werden kann.

FreeLLMAPI ist ein offener, selbst gehosteter Router, der kostenlose Pläne von Dutzenden von KI-Anbietern unter einer OpenAI-kompatiblen /v1-Adresse sammelt. Anstelle von dreißig Schlüsseln, dreißig Grenzwerten und dreißig Stellen, an denen eine Anfrage fehlschlagen kann, haben Sie ein lokales Gateway und einen einheitlichen Schlüssel. Der Router wählt selbst ein verfügbares Modell aus, schaltet bei Fehler 429 oder 5xx auf das nächste um und stellt sicher, dass Anfragen die Kontingente der Gratistarife nicht überschreiten.

In diesem Beitrag beschreibe ich die Installation von FreeLLMAPI, das Hinzufügen von Anbietern und die Verbindung des Gateways mit OpenCode.

Was Sie brauchen

Zum Arbeiten benötigen Sie vier Dinge:

• OpenCode installiert. Wenn der Agent noch nicht installiert ist, habe ich den Installationsvorgang in einem separaten Hinweis zu OpenCode und DeepSeek besprochen.
• FreeLLMAPI läuft. Der einfachste Weg ist die Installation einer Desktop-Anwendung oder eines Docker-Containers.
• Node.js 20.18 oder höher. Dies wird für den CLI-Generator benötigt, der OpenCode konfiguriert. OpenCode selbst kann ohne Node installiert werden.
• Schlüssel von mindestens einem Anbieter. Geeignet sind kostenlose Pläne von Google AI Studio, Groq, Cerebras, Mistral, OpenRouter, NVIDIA, HuggingFace und anderen Diensten aus dem Katalog.

FreeLLMAPI installieren

Das Projekt verfügt über mehrere Installationspfade. Wählen Sie diejenige, die für Ihr System bequemer ist.

Desktop-Anwendung

Die einfachste Option für Windows und macOS ist der vorgefertigte Installer auf der Release-Seite. Unter Windows ist es .exe, unter macOS ist es .dmg für Apple Silicon oder Intel. Die Anwendung befindet sich im Fach und hebt den Router zusammen mit dem Bedienfeld lokal an.

Für die Desktop-Version ist kein Passwort erforderlich: Das Panel meldet sich selbstständig über ein verstecktes lokales Konto an. Die einzigen Anmeldeinformationen, die Sie benötigen, sind der einheitliche Schlüssel aus dem Popup-Fenster in der Taskleiste oder aus der Kopfzeile der Seite „Schlüssel“.

Die Anwendungsdaten liegen in einem Verzeichnis:

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

Docker

Wenn Docker bereits installiert ist, wird der Server mit einem Befehl hochgefahren. Das Skript erstellt das Verzeichnis ~/freellmapi, generiert einen Verschlüsselungsschlüssel, lädt das Bild herunter und startet den Container:

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

Das erneute Ausführen des Skripts ist sicher: Die .env-Datei und der Verschlüsselungsschlüssel werden gespeichert und der Container wird auf die neueste Version aktualisiert. Unter Windows funktioniert diese Methode in WSL oder einer beliebigen Bash-Umgebung.

Nach dem Start öffnet sich das Panel unter:

http://localhost:3001

Für die Serverinstallation müssen Sie ein Konto mit einer E-Mail-Adresse und einem Passwort erstellen. Wenn das Passwort vergessen wird, wird der Reset-Code im Containerprotokoll ausgedruckt:

docker compose logs -f freellmapi

Docker Compose

Wenn Sie die Konfiguration in Git beibehalten und den Start manuell verwalten möchten, reicht normales Compose aus. Unter macOS und 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

In 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

Der ENCRYPTION_KEY-Schlüssel ist erforderlich: Er wird zum Verschlüsseln von Anbieterschlüsseln in der SQLite-Datenbank verwendet. Sie können es nicht im Handumdrehen ändern – alte Geheimnisse werden nicht mehr entschlüsselt. Für die Rotation verfügt das Projekt über einen separaten Befehl rotation-encryption-key.

Wird von der Quelle ausgeführt

Zur Entwicklung oder zum Debuggen können Sie das Projekt über Node.js ausführen:

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

In diesem Modus werden die API und das Panel auf Port 3001 und die Vite-Schnittstelle auf 5173 hochgefahren.

Erststart und Anbieterschlüssel

Öffnen Sie das Panel, gehen Sie zur Seite Schlüssel und fügen Sie die Schlüssel der von uns verwendeten Dienste hinzu. Für jeden Anbieter gibt es in der Schnittstelle einen Link zur Registrierung und einen Hinweis, wo man den Schlüssel bekommt. Es reicht aus, mit ein oder zwei zu beginnen: zum Beispiel Google AI Studio und Groq.

Nach dem Hinzufügen wird der Schlüssel einem Gesundheitscheck unterzogen. Wenn der Anbieter mit einem Fehler geantwortet hat, bleibt der Schlüssel in der Liste, wird aber als fehlerhaft markiert – er kann erneut überprüft oder gelöscht werden.

Als nächstes sollten Sie zur Seite Modelle gehen und sehen, welche Modelle verfügbar sind. Dort können Sie auch die Routing-Strategie und die Reihenfolge der Fallback Chain – der Kette, entlang derer der Router bei Fehlern und Limits geht – konfigurieren. Das Auto-Modell bedeutet, dass die Auswahl vom Router selbst getroffen wird. Darüber hinaus stehen Optionen wie auto:fast, auto:smart und benannte Profile für bestimmte Aufgaben zur Verfügung.

Es lohnt sich auch zu prüfen, ob es Modelle in der Kette gibt, die Tools unterstützen. OpenCode nutzt aktiv Toolaufrufe, und ein Modell ohne diese Funktion kann keine Dateien lesen oder Befehle normal ausführen.

Der Unified-Schlüssel befindet sich dort, auf der Seite Schlüssel oder in der Taskleiste der Desktop-Anwendung. Es sieht aus wie eine Zeichenfolge mit einem Präfix:

freellmapi-...

Es ist dieser Schlüssel und nicht die Schlüssel einzelner Anbieter, der in OpenCode angezeigt wird.

Mit OpenCode verbinden

FreeLLMAPI verfügt über einen Konfigurationsgenerator, der selbst das Modellverzeichnis vom laufenden Gateway liest, eine Sicherungskopie der vorhandenen Konfiguration erstellt und den Anbieter sorgfältig hinzufügt.

Legen wir zunächst den einheitlichen Schlüssel auf die Umgebungsvariable fest. Der Generator liest es anstelle eines separaten Flags, sodass das Geheimnis nicht im Befehlsverlauf landet.

Unter macOS und Linux:

export FREELLMAPI_API_KEY=freellmapi-YOUR_KEY

In Windows PowerShell:

$env:FREELLMAPI_API_KEY="freellmapi-YOUR_KEY"

Schauen wir uns nun an, was genau aufgezeichnet wird:

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

Wenn diff zufriedenstellend ist, wiederholen Sie den Befehl ohne das Flag:

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

Der Generator schreibt die globale OpenCode-Konfiguration:

~/.config/opencode/opencode.json

Darin erscheint der Freellmapi-Anbieter mit dem @ai-sdk/openai-kompatiblen Paket, der Basisadresse http://localhost:3001/v1 und einer Karte von Modellen aus dem Live-Katalog. Das Standardmodell wird freellmapi/auto.

Der Schlüssel selbst landet nicht in der Datei: Die Konfiguration enthält die Ersetzung {env:FREELLMAPI_API_KEY}. Daher muss die Variable beim Start des Agenten gesetzt bleiben:

opencode

Diese Methode ist auch praktisch, da das Geheimnis nicht in der Konfiguration und auch nicht in Git landet. Bei CI und einmaligen Läufen ist dies korrekter als das Speichern des Schlüssels in einer Datei.

Manuelle Einstellung

Wenn Sie den Generator nicht ausführen möchten, können Sie den Anbieter manuell in opencode.json beschreiben. Die Mindestoption sieht so aus:

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

Das Modellfeld auf der obersten Ebene ist wichtig: Ohne es verwendet OpenCode möglicherweise weiterhin das vorherige Modell oder wählt bei einer Neuinstallation nichts aus. Es ist besser, den Kontext und die Ausgabegrenzen aus der Gateway-Antwort zu übernehmen, als sie zu erfinden:

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

Sie können der Modellliste bestimmte Kennungen hinzufügen, wenn Sie manuell zu ihnen wechseln müssen. Aber für den Alltag reicht Auto aus: Der Router wählt selbst ein Live-Modell aus und schaltet um, wenn das Limit erreicht ist.

So verwenden Sie es

Nach dem Start von Opencode öffnet sich die Liste der Modelle mit einem bekannten Befehl:

/models

Es wird einen FreeLLMAPI-Anbieter und ein Auto-Modell geben. Dann geht die Arbeit wie gewohnt weiter: Wir beschreiben die Aufgabe, geben Dateien per @ an, wechseln den Planungsmodus mit der Tab-Taste, machen die Änderungen mit dem /undo-Befehl rückgängig. Für ein neues Projekt ist es sinnvoll, /init auszuführen, damit der Agent AGENTS.md erstellt.

Ein paar praktische Tipps:

• Routing. Belassen Sie es für Routinezwecke auf „Auto“. Wenn Sie Geschwindigkeit benötigen, versuchen Sie es mit auto:fast, wenn die Qualität auto:smart oder ein bestimmtes starkes Modell aus dem Katalog ist.
• Diagnose Jede Gateway-Antwort enthält einen X-Routed-Via-Header mit dem Namen des Anbieters und Modells, der die Anfrage tatsächlich bedient hat. Es zeigt, wohin der Router die Aufgabe gesendet hat.
• Analytics. Auf der Analytics-Seite zeigt das Panel das Volumen der Anfragen, den Erfolg, p50/p95-Verzögerungen und den Token-Verbrauch nach Anbieter an.
• Kontinuität des Dialogs. Wenn Sie mitten in einem Gespräch das Modell wechseln, kann das Gateway eine kurze Notiz über die Übertragung des Kontexts hinzufügen. Aktiviert durch die Variable FREELLMAPI_CONTEXT_HANDOFF=on_model_switch.

Wenn OpenCode in einem Container und FreeLLMAPI auf einem Host ausgeführt wird, verweist localhost auf den Container selbst. In diesem Fall müssen Sie host.docker.internal oder eine andere Adresse verwenden, auf die über den Container in der Basis-URL zugegriffen werden kann.

Worauf Sie achten sollten

FreeLLMAPI ist kein Ersatz für kostenpflichtige Modelle und kein Service mit SLA. Es ist eine Möglichkeit, kostenlose Pläne in einem übersichtlichen Gateway zu bündeln. Daher gibt es mehrere Einschränkungen:

• Qualität schwankt. Kostenlose Tarife enden und am späten Abend, kurz vor der Erschöpfung der Tageskontingente, wechselt der Router möglicherweise zu schwächeren Modellen. Kontingente werden normalerweise um Mitternacht UTC zurückgesetzt.
• Latenzen sind variabel. Verschiedene Anbieter reagieren unterschiedlich und bei der Umstellung auf ein Backup-Modell kann die Anfrage merklich länger dauern.
• Es gibt keine Flaggschiff-Modelle. Gute, aber nicht erstklassige Modelle sind in kostenlosen Tarifen erhältlich. Bei komplexen Architekturen ist dies eine Überlegung wert.
• Das Gateway muss ausgeführt werden. Wenn die Anwendung oder der Container gestoppt wird, erhält OpenCode keine Antwort. Durch den automatischen Start der Anwendung in der Taskleiste oder einen Neustart der Containerrichtlinie wird dieses Problem gelöst.
• Das Projekt ist für einen Benutzer konzipiert. Anbieterschlüssel werden lokal und verschlüsselt gespeichert, ein gemeinsames Panel für mehrere Personen ist jedoch nicht das Szenario für dieses Tool. Der einheitliche Schlüssel und .env sollten auf die gleiche Weise wie ein normales Geheimnis geschützt werden.

Und noch eine Nuance: Der Modellkatalog aktualisiert sich selbst, die kostenlose Installation erhält jedoch mit einer Verzögerung von etwa dreißig Tagen einen Snapshot des Katalogs. Der kostenpflichtige Premium-Plan beschleunigt das Update, es ist jedoch keine Einarbeitung in das Projekt erforderlich – der Router selbst bleibt kostenlos und offen.

Links

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/

Quellen

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/