OmniRoute installieren: Schnellstart & Claude Code

OmniRoute ist ein OpenAI-kompatibles KI-Gateway. Es bündelt viele vorgelagerte Modellanbieter hinter einer lokalen API, sodass Claude Code, Codex CLI, IDE-Erweiterungen und Ihre eigenen Skripte nur einmal konfiguriert werden müssen. Diese Seite zeigt den kürzesten Weg von der Installation bis zur ersten erfolgreichen Anfrage; die ausführlichen Themenanleitungen liegen auf einer eigenen Website.

Merken Sie sich diese beiden Adressen

• Dashboard: http://localhost:20128
• OpenAI-kompatible Base URL: http://localhost:20128/v1

In Clients tragen Sie die zweite Adresse ein, nicht die des Dashboards.

Voraussetzungen

• Node.js >=22.22.2 <23 oder >=24.0.0 <27; empfohlen wird Node.js 24 LTS. Außerhalb dieses Bereichs kann das Dashboard eine leere Seite oder Fehler zu nativen Modulen anzeigen. Falls nötig, installieren Sie zuerst Node.js.
• Der lokale Port 20128 ist frei.
• Mindestens ein Konto oder Schlüssel eines vorgelagerten Anbieters, den Sie über OmniRoute routen möchten.

Installieren und starten

Wählen Sie eine Methode:

# npm (empfohlen)
npm install -g omniroute
omniroute

# Docker
docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

Sie können auch ein Desktop-Installationspaket für Windows, macOS oder Linux von den OmniRoute GitHub Releases herunterladen. :latest verweist auf das neueste veröffentlichte stabile Release; für reproduzierbare Deployments sollten Sie eine genaue Version festlegen.

Öffnen Sie nach dem Start http://localhost:20128. Das Anmeldepasswort wird über die Umgebungsvariable INITIAL_PASSWORD bestimmt; in der Self-Hosting-Konfiguration des Upstream-Projekts wird es beim ersten Start erzeugt und ins Log geschrieben, und mit Docker finden Sie es über docker logs omniroute | grep -i password. Setzen Sie ein eigenes, starkes Passwort, bevor Sie den Dienst im Netzwerk erreichbar machen.

Anbieter verbinden und Schlüssel erstellen

1. Gehen Sie im Dashboard zu Providers → Add Provider und verbinden Sie Ihren Anbieter.
2. Erstellen Sie auf der Seite API Keys einen neuen Schlüssel und bewahren Sie ihn auf, denn er wird nur einmal angezeigt. Dieser Schlüssel dient dazu, dass Clients auf OmniRoute zugreifen, und ist kein Schlüssel eines vorgelagerten Anbieters.

Die Upstream-Dokumentation nennt einige kostenlose Anbieter, die keinen Schlüssel brauchen. Verfügbarkeit und Bedingungen ändern sich, prüfen Sie daher die Bedingungen des jeweiligen Dienstes, bevor Sie sich darauf verlassen.

Dienst überprüfen

export OMNIROUTE_API_KEY="paste the key you created on the API Keys page"

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}"

Eine Modellliste bedeutet, dass der OpenAI-kompatible Endpunkt und die Authentifizierung funktionieren. Senden Sie danach eine minimale Chat-Anfrage, um zu bestätigen, dass ein Modell wirklich geroutet werden kann:

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Reply with ok." }]
  }'

Mit auto wählt OmniRoute den Anbieter nach Geschwindigkeit, Kosten und Verfügbarkeit aus. Sie können auch eine konkrete Modell-ID aus der Antwort von /v1/models verwenden.

Werkzeuge anbinden

Tragen Sie in jedem Werkzeug, das das OpenAI-Format spricht, Folgendes ein:

Base URL: http://localhost:20128/v1
API Key:  the OmniRoute key you created
Model:    auto

OmniRoute bringt außerdem Starter mit einem einzigen Befehl mit, zum Beispiel omniroute launch-codex --model auto; die allgemeine Form omniroute run <target> unterstützt claude, codex, aider, goose, opencode, qwen und gemini. Wenn Sie ein Agent-CLI in HagiCode verwenden möchten, richten Sie es zuerst mit der Installation von AI Agent CLI ein.

Häufige Probleme

• Leeres Dashboard oder Warnung zu einer nicht unterstützten Node.js-Version: Wechseln Sie zu Node.js 24 LTS, führen Sie npm install -g omniroute erneut aus und starten Sie dann omniroute.
• better-sqlite3 unter npm 11 nicht gefunden: npm 11 blockiert standardmäßig die Installationsskripte optionaler Abhängigkeiten; bauen Sie das Modul gemäß der Fehlerbehebungsanleitung von Hand neu.
• slice is not valid mach-o file unter macOS: Führen Sie npm rebuild better-sqlite3 in $(npm root -g)/omniroute/app aus und starten Sie erneut.

Vollständige Dokumentation

OmniRoute-Dokumentation auf Deutsch öffnen

• Schnellstart: OmniRoute in 3 Minuten zum Laufen bringen
• OmniRoute für Claude Code konfigurieren
• OmniRoute mit Docker bereitstellen
• OmniRoute für Codex CLI konfigurieren
• Fehlerbehebung