OmniRoute von null: ein lokales kostenloses AI-Gateway für Claude, GPT, Gemini und DeepSeek

Cursor, Claude Code, Codex und Gemini CLI merken sich jeweils eigene Adresse und eigenes Geheimnis. Kommen Anbieter dazu, verteilen sich Limits und „heute 429“ über die Konfigurationen. OmniRoute zieht das auf eine OpenAI-kompatible Adresse auf Ihrem Rechner zusammen. Clients merken sich http://127.0.0.1:20128/v1. Claude, GPT, Gemini, DeepSeek und der Rest des Katalogs hängen im Dashboard. Die Lizenz ist MIT. Diese Anleitung folgt release/v3.8.53. Ports, Befehle und Routing entsprechen dieser README. Die Anbieterzahl bewegt sich mit der Version.

„Kostenlos“ heißt: für die Gateway-Software fällt keine Lizenzgebühr an. Das Kontingent liegt auf den Anbieterkonten, die Sie verbinden. Das Projekt zeigt unter /dashboard/free-tiers eine Schätzung fremder Gratisstufen und schreibt, die Zahl sei eine Summe, keine Token-Gutschrift von OmniRoute. Abos, die Sie schon bezahlen, können dieselbe Adresse über ihren eigenen Kontoablauf nutzen. Listenpreise stehen in der monatlichen Rechnung der Coding-Werkzeuge und in den OpenRouter-Preisen. OpenRouter ist ein gehosteter Router. OmniRoute ist das Gateway auf Ihrem Rechner.

Wo das Gateway sitzt

Stellen Sie es sich als eine Buchse vor, die nur auf Ihrem Rechner läuft. Upstream bleiben OpenAI, Anthropic, Google, DeepSeek oder ein anderer Kataloganbieter. Downstream ist jeder Client, der OpenAI Chat Completions oder Responses spricht. Die Doku zu v3.8.53 nennt etwa 375 Anbieter und etwa 1.475 rohe Modell-IDs, ein Teil davon mit Free-Tier-Hinweis. Diese Zahlen werden neu geprüft und gehören in den Live-Katalog, nicht in einen alten Screenshot.

• Sie halten zwei Schlüssel.Der Anbieter-API-Schlüssel oder die OAuth-Sitzung bleibt in OmniRoute. Cursor und Skripte nutzen den Gateway-Schlüssel aus Dashboard → Endpoints.
• Modell-IDs gibt es nach dem Verbinden.Rufen Sie zuerst /v1/models auf. Beispiele in der README sehen aus wie openai/gpt-5.4 und glm/glm-5.2. Nehmen Sie die ID, die Ihre Liste wirklich liefert.
• Die Client-Liste ist breit.Genannt werden Claude Code, Codex, Cursor, Cline, Continue, OpenCode, Copilot, OpenClaw und weitere. Wer eine eigene OpenAI-Base-URL setzt, braucht nur die Adresse. omniroute run startet sieben der CLIs.

Installation von null: npm und Docker

Auf dem Rechner braucht es Node.js. Der kurze Weg:

npm install -g omniroute
omniroute

npm warn ERESOLVE und Peer-Warnungen darf man laut Doku zuerst ignorieren. Das Dashboard öffnet http://127.0.0.1:20128, die API liegt unter http://127.0.0.1:20128/v1. Nur der Proxy, ohne Dashboard: omniroute serve --headless oder OMNIROUTE_HEADLESS=1.

npm 11 muss Installationsskripte erlauben

npm 11 kann Lebenszyklus-Skripte blockieren. OmniRoutes postinstall muss laufen, damit die nativen Laufzeitdateien da sind. Die Allow-List für 3.8.53:

npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroute

Nennt npm andere Pakete, nehmen Sie diese Liste. Erlauben heißt: die Installationsskripte dieser Pakete laufen. Tun Sie das, nachdem Sie der Quelle vertrauen. Auf CI oder einem langsamen Rechner überspringt OMNIROUTE_SKIP_POSTINSTALL=1 nur das native SQLite-Aufwärmen. Der Binärkopie-Schritt läuft weiter.

Docker für einen Coding-Agent dimensionieren

Der Image-Name in der Doku ist weiter diegosouzapw/omniroute. :latest folgt der höchsten veröffentlichten stabilen SemVer, nicht git main. Für dauerhafte Setups eine Version festnageln. Das veröffentlichte Beispiel bindet den Loopback:

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
  -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

Das Image setzt den Heap standardmäßig auf 1024 MB, genug für Dashboard und kurzen Chat. Claude Code und Codex rufen POST /v1/responses. Lange Kontexte brauchen einen größeren V8-Heap, sonst endet der Prozess mit einem fatalen Speicherfehler. Ein Coding-Agent ist der Heap 8192 und mindestens 10g Container im Befehl oben. Zwei überlappende lange Anfragen gehen auf Heap 10240–12288 und Container 12–16g. Apple Silicon nutzt den arm64-Build. Das Volume omniroute-data enthält Geheimnisse. Sichern und löschen Sie es als vertrauliche Daten.

Claude, GPT, Gemini und DeepSeek verbinden

Öffnen Sie Providers, wählen Sie einen Anbieter, den Sie nutzen dürfen, und fügen Sie einen API-Schlüssel ein oder schließen Sie dessen Kontoablauf ab. OmniRoute eröffnet die Laborkonten nicht für Sie:

Gratisstufen sind eine eigene Liste. Sie sind keine Synonyme für diese vier Schlüssel. Der Ersteinrichtungsassistent kann „kostenlose Anbieter einrichten“ anbieten. Er baut die Liste aus dem aktuellen Katalog ohne Anmeldung und legt eine Verbindung erst an, nachdem Sie jede bestätigt haben. Namen, die dort standen, sind unter anderem Pollinations, Cloudflare AI und die DeepSeek-Gratisstufe von SiliconFlow. Bedingungen, Region und ob die Stufe noch existiert, entscheidet der Anbieter. Ein älterer Text über „Claude ohne Schlüssel“ kommt nicht in auto, wenn der Anbieter tos: avoid trägt. Lesen Sie die Free-Tiers-Seite auf die Zulässigkeit dieses Tages, bevor Sie sich darauf verlassen.

Web-Cookie-Anbieter wie Gemini Web brauchen zusätzlich eine Browser-Laufzeit. Das npm-Paket enthält Playwright, nicht die Chromium-Binärdatei. Folgen Sie dem Playwright-Chromium-Hinweis im Repo vor dem ersten Aufruf, sonst scheitert die Anfrage in der Browserschicht.

Eine Adresse für IDE und CLI

Kopieren Sie den Gateway-Schlüssel aus Endpoints. Dann:

Base URL: http://127.0.0.1:20128/v1
API Key:  (Dashboard → Endpoints)
Model:    auto

Prüfen Sie die Modellliste, bevor die IDE spricht:

curl http://127.0.0.1:20128/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

curl http://127.0.0.1:20128/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'

Cursor, Cline, Continue und jedes Plugin mit eigener OpenAI-Base-URL nehmen diese drei Zeilen. Clients ohne eigenen Header können die tokenisierte Kompatibilitäts-URL nutzen, zum Beispiel http://127.0.0.1:20128/vscode/YOUR_KEY/chat/completions. Kann der Client einen Header senden, bleibt Authorization: Bearer der bevorzugte Weg.

Sie müssen nicht jede CLI-Konfiguration von Hand ändern. Der Ein-Befehl-Start setzt die Zugangsdaten in diesen Prozess. Qwen und Gemini bekommen zusätzlich ein wegwerfbares, isoliertes Home:

omniroute run claude --model auto
omniroute run codex  --model auto
omniroute run gemini --model auto
omniroute configure codex

omniroute run deckt Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code und Gemini CLI ab. configure schreibt Anbieter und Modell in die eigene Konfiguration des Werkzeugs. Dokumentierte Ziele sind codex, claude, opencode, qwen, aider, goose, gemini, cline, continue und kilo. --dry-run zeigt Umgebung und Argumente, ohne auszuführen. --api-key-env NAME lässt das Geheimnis im Namen einer Umgebungsvariable, damit es nicht in der Shell-Historie landet.

auto, Fallback und wer draußen bleibt

auto wählt unter Verbindungen, die schon verbunden und zulässig sind. Eine frische Installation ohne Anschluss kann kein zulässiges Ziel haben. Das ist erwartet. Strategie, Anbieter und Latenz kommen im Header X-OmniRoute-Decision zurück. Lesen Sie diesen Header vor dem Client-Log.

• Kontingentbewusster Fallback.Ist eine Verbindung erschöpft, kann die Planung auf eine andere mit Rest wechseln. v3.8.53 gewichtet nach Restkontingent und versucht, ein Gespräch auf derselben Verbindung zu halten.
• Eine Abo-Route kann geschlossen fehlschlagen.Die dokumentierte Subscription-Combo verbraucht nur das Abo-Kontingent, das Sie schon bezahlen. Ist es weg, stoppt die Anfrage. Sie fällt nicht auf einen anderen Schlüssel, der abrechnet. Mischen Sie kostenpflichtige API-Schlüssel und Abo-Schlüssel nicht in eine Combo, die irgendwohin ausweicht.
• tos: avoid bleibt standardmäßig draußen.Ein erfolgreiches Verbinden ist keine Mitgliedschaft in auto. Um einen Gateway-Schlüssel auf ein Modell zu nageln, setzen Sie dessen forcedModel, statt im Client eine Upstream-URL festzuschreiben.

Kompression ist eine optionale Pipeline und für den Client durchsichtig. Die Doku beschreibt sie als kombinierbare Engines. Was wirklich lief, steht im Antwort-Header X-OmniRoute-Compression. Die Ersparnis hängt von Modell und Anfrage ab. Die Spanne in der README ist eine Projektangabe, keine Garantie pro Aufruf. Speicher ist standardmäßig aus. Das Maskieren von Zugangsdaten ist opt-in.

Auf einem Cloud Mac: Loopback plus SSH

Das Gateway passt auf einen Mac, der an bleibt: Port 20128 auf dem Loopback, und diesen Port per SSH auf den Laptop. Ein Cloud Mac hat eine feste Region und SSH; Apple Silicon kann das offizielle arm64-Image fahren. Binden Sie die Verwaltungsoberfläche nicht an 0.0.0.0.

ssh -N -L 20128:127.0.0.1:20128 user@your-cloud-mac

Steht der Tunnel, nutzen Cursor oder omniroute run auf dem Laptop weiter http://127.0.0.1:20128/v1. Es sieht lokal aus. Die Bytes landen auf dem Loopback des Cloud Mac. Anbietergeheimnisse bleiben im Cloud-Volume oder im Benutzerverzeichnis, nicht in Git. Läuft OpenClaw schon auf diesem Mac, zeigen Sie dessen Modelladresse auf dasselbe /v1 und lassen eine einzige Kopie der Anbieterschlüssel im Gateway.

Braucht das Dashboard eine Anmeldung, bietet die Doku optionales OIDC. Die Passwortanmeldung bleibt. Fernsteuerung hat zusätzlich bereichsbegrenzte Tokens (connect, contexts, tokens) im Remote Mode des Projekts. Nutzen Sie diesen Weg. Hängen Sie das Dashboard nicht an eine öffentliche IP, um einen Schritt zu sparen.

Was Sie prüfen, wenn es stockt

1. /v1/models ist leer.Keine Anbieterverbindung hat geklappt, oder der Client hat den Anbieterschlüssel dort eingesetzt, wo der Gateway-Schlüssel hingehört.
2. auto meldet keine Route.Es sind nur ausgeschlossene Verbindungen da, oder die Gratisstufe ist heute nicht zulässig. Nehmen Sie einen bezahlten Schlüssel, von dem Sie wissen, dass er funktioniert, oder eine konkrete ID aus /v1/models.
3. Nach der globalen Installation fehlt ein natives Modul.Neu installieren mit --allow-scripts von npm 11 und den Paketnamen aus dieser Warnung.
4. Ein Coding-Agent stirbt in Docker mitten in der Anfrage.Heben Sie OMNIROUTE_MEMORY_MB und --memory auf die Stufe für Coding-Agents. Die 1024 MB lassen Sie dem Dashboard.
5. Der erste Aufruf eines Web-Anbieters scheitert.Installieren Sie Playwright-Chromium und versuchen Sie es erneut. Die Routing-Regel ändern Sie danach.
6. Die Zahlen wirken alt.375 Anbieter und 1.475 Modell-IDs sind die Angaben der v3.8.53-Doku. Nach einem Upgrade zählen Dashboard und README.

FAQ

Kurz: Die Software ist kostenlos, das Kontingent gehört dem Anbieter; die Adresse ist /v1 auf dem lokalen Port 20128; auto nutzt nur zulässige Verbindungen; Coding-Agents in Docker brauchen mehr Speicher; der Port bleibt auf dem Loopback und wird per SSH weitergeleitet. Die vollständigen Fragen stehen in den FAQ-Strukturdaten im Seitenkopf.