Schritt-für-Schritt-Anleitung: Mit einem einzigen Schlüssel alle Agenten verbinden und mit dem Open-Source-Projekt magpie ein einheitliches API-Gateway einrichten (am Beispiel von Claude Code, Codex, Pi und Hermes)

Anmerkung des Autors: Dieses Tutorial lässt sich Schritt für Schritt umsetzen. Wenn du es vollständig durchliest und mitmachst, hast du am Ende eine Konfiguration nach dem Prinzip „ein Key, eine Gateway-Adresse – und so viele Agents, wie du installiert hast“. Wenn du später das Modell wechselst oder den Key austauschst, musst du nur eine einzige Stelle anpassen.

Bevor du loslegst: Das erwartet dich

• Ziel: Alle Programmier-Agents auf deinem Rechner verwenden denselben API-Key und dieselbe Upstream-Adresse. In diesem Tutorial zeigen wir das am Beispiel von Claude Code, Codex, Pi und Hermes. Du kannst so viele Agents anbinden, wie du installiert hast.
• Zeitaufwand: etwa 30 Minuten (ohne Registrierung und Netzwerk-Downloads)
• Voraussetzungen: ein APIYI-Token (alternativ ein beliebiger OpenAI- oder Anthropic-kompatibler API-Proxy-Dienst oder ein offizieller Key), ein Computer, auf dem sich Befehle ausführen lassen, und mindestens ein installierter Agent
• Schwierigkeitsgrad: ★★☆☆☆. Ein paar Mausklicks und Kopieren und Einfügen reichen aus – Befehle musst du während des gesamten Vorgangs nicht eingeben.

Überblick über die Schritte

In drei Minuten verstanden: Was macht magpie eigentlich dazwischen?

Wenn Sie einfach nur „der Anleitung folgen“ möchten, können Sie diesen Abschnitt überspringen. Drei Minuten Lesezeit sparen Ihnen später aber wahrscheinlich einiges an Zeit bei der Fehlersuche.

Die Anforderungen der verschiedenen Agents an das jeweilige Upstream-Modell unterscheiden sich stark. Wer alles manuell konfiguriert, muss für jedes installierte Tool eine eigene Konfiguration pflegen. Hier sind vier besonders verbreitete Beispiele:

Genau dieses Problem löst magpie (Repository: github.com/yetone/magpie, Motto: „Every agent’s model. One place.“): Das Tool bündelt die Verwaltung in einer Oberfläche. Dort legen Sie fest, welcher Agent welches Modell und welchen Key verwendet. Anschließend passt magpie die nativen Konfigurationen der jeweiligen Tools an.

Kurz gesagt:

• magpie übernimmt die Verteilung: Es legt fest, welches Modell Claude Code und welches Codex verwendet.
• Das Gateway übernimmt die Protokolle: Es leitet Anfragen im Anthropic-, OpenAI- oder Gemini-Format an den jeweiligen Modellanbieter weiter.

Deshalb sollte Ihr Upstream-Gateway möglichst mehrere Protokolle unterstützen

Die ideale Aufgabenteilung lautet: „magpie übernimmt die Verteilung, das Gateway die Protokolle“. Unterstützt das Gateway nur das OpenAI-kompatible Format, muss Claude Code zusätzlich über eine Protokollkonvertierung angebunden werden. Das macht die Verbindungskette länger und erhöht das Risiko, dass das Format für Tool-Aufrufe nicht einheitlich ist.

Bei APIYI sind drei wichtige Protokolle mit einem einzigen Token nutzbar: OpenAI-kompatibel, nativ im Anthropic-Format und im Gemini-Format – alle lassen sich mit demselben Key aufrufen. (Welche Protokolle genau unterstützt werden, entnehmen Sie bitte den Angaben in der Konsole.) So muss magpie nur ein Upstream anbinden, über das alle Agents direkt zugreifen können. Separate Konten und Abrechnungen bei den einzelnen Anbietern entfallen.

Welche der drei Möglichkeiten passt zu Ihnen?

Die manuelle Konfiguration ist am einfachsten umzusetzen. Mit jedem zusätzlichen Tool verteilen sich die Keys jedoch auf weitere Dateien, was den Aufwand für Rotation und Fehlersuche deutlich erhöht. Ein Skript mit Umgebungsvariablen kommt ohne zusätzliche Abhängigkeiten aus und ist in wenigen Dutzend Zeilen eingerichtet. Allerdings lassen sich damit nicht verschiedenen Agents unterschiedliche Modelle zuweisen. Anforderungen wie „Claude Code soll Claude nutzen, Codex GPT und Hermes ein günstiges Modell“ lassen sich mit einer zentralen Verwaltungslösung wie magpie am bequemsten umsetzen.

Schritt 1: API-Schlüssel holen und kopieren

1.1 Token in der APIYI-Konsole erstellen

Erstelle in der APIYI-Konsole (apiyi.com) ein Token und kopiere es.

Dafür musst du keinen einzigen Befehl eingeben. Im gesamten Ablauf kommt dieser API-Schlüssel nur einmal zum Einsatz: Du fügst ihn im Bereich „Anbieter“ von magpie ein (Schritt 3). Anschließend legt magpie die Konfigurationsdateien für die einzelnen Agents automatisch an. Du musst weder eine Umgebungsvariable mit export setzen noch Dateien wie config.toml oder settings.json ändern.

🚀 Du hast noch kein Token? Registriere dich bei APIYI unter apiyi.com und sichere dir ein Testguthaben. Damit kannst du die wichtigsten Tools mit einem Token ausprobieren und anschließend entscheiden, welche Modelle du langfristig nutzen möchtest.

1.2 Zwei Adressen griffbereit halten

In Schritt 3 musst du beim Einrichten des Anbieters eine der beiden Adressen auswählen:

✅ Das solltest du am Ende dieses Schritts erledigt haben: Das Token befindet sich in der Zwischenablage, und du weißt, welche Adresse du in Schritt 3 eintragen musst.

Schritt 2: magpie installieren und die beiden Seiten kennenlernen

Informationen zum Quellcode, zur Installation und zum Konfigurationsformat von magpie findest du in der README des offiziellen Repositories (github.com/yetone/magpie). Das Projekt entwickelt sich schnell weiter, daher können sich Installationsbefehle und Feldnamen je nach Version ändern. Die folgenden Screenshots und die Reihenfolge der Schritte bleiben jedoch dauerhaft relevant.

Nach der Installation und dem Start erscheint ein Fenster mit einer Navigation auf der linken Seite. Für diese Anleitung brauchst du nur zwei Seiten: Agent (welches Modell welcher Agent nutzt) und Anbieter (wo der API-Schlüssel hinterlegt ist).

① Agent in der linken Navigation ist die zentrale Steuerung für alle deine Agents:

Abbildung 1 · Agent-Seite: Jedes Tool hat eine eigene Zeile. Mit dem Schalter rechts aktivierst du die Anbindung an magpie; daneben befindet sich das Dropdown-Menü für die Modellauswahl.

Auf dieser Seite solltest du drei Dinge erkennen:

② Unter Anbieter in der linken Navigation hinterlegst du den API-Schlüssel des übergeordneten Dienstes. Mehr dazu im nächsten Abschnitt.

Wenn du dir zuerst ansehen möchtest, wie die Konfigurationsdatei von magpie aufgebaut ist, wirf einen Blick auf die Strukturen providers und agents in der offiziellen README. Vereinfacht gesagt: Du gibst dem übergeordneten Dienst einen Namen, trägst base_url und API-Schlüssel ein und weist dann jedem Agent ein Modell zu. Im Alltag erledigst du aber alles direkt im Fenster: magpie übernimmt das Schreiben der nativen Konfigurationen für die einzelnen Tools. Das ist zuverlässiger, als YAML-Dateien von Hand zu bearbeiten.

✅ Das solltest du am Ende dieses Schritts erledigt haben: Das Fenster lässt sich öffnen, und in der linken Navigation sind die beiden Einträge „Agent“ und „Anbieter“ zu sehen.

Schritt 3: Deinen Key unter „Anbieter“ hinterlegen

3.1 Zur Anbieterseite wechseln

Klicke links auf Anbieter (roter Rahmen ① in Abbildung 2). Klicke dann oben rechts auf + Anbieter hinzufügen (roter Rahmen ②):

Abbildung 2 · Anbieterseite: Über die Navigation links zu „Anbieter“ wechseln. Oben rechts ist „+ Anbieter hinzufügen“ der einzige Einstieg.

Bereits hinzugefügte Anbieter werden hier als Karten angezeigt. In der zweiten Zeile jeder Karte stehen die Adresse und die Anzahl der verfügbaren Modelle, zum Beispiel api.apiyi.com · 11 Modelle. Wenn du prüfen möchtest, ob alles funktioniert, schau zuerst nach, ob hier eine Zahl angezeigt wird.

3.2 Welche Art von Anbieter solltest du wählen?

Wenn du auf „+ Anbieter hinzufügen“ klickst, wird ein Auswahlfenster mit mehreren Gruppen angezeigt (Abbildung 3):

Abbildung 3 · Fenster zum Hinzufügen eines Anbieters: fünf Quellen – Abonnement, Anbieter, API-Proxy-Dienst, lokaler Rechner und magpie auf einem anderen Computer

Die Gruppen im Auswahlfenster stehen für fünf verschiedene Arten von Zugangsdaten:

Wenn du APIYI verwendest: Der OpenAI-kompatible Endpunkt entspricht der standardmäßigen Proxy-Variante. Wähle den passenden Eintrag in der Gruppe API-Proxy-Dienst. Wenn du einen eigenen OpenAI- oder Anthropic-kompatiblen Key hast, klicke stattdessen ganz unten auf + Benutzerdefinierter Anbieter (roter Rahmen in Abbildung 3) und trage die Adresse und den Key ein. Verwende als Adresse https://api.apiyi.com/v1 (für native Anthropic-Anfragen https://api.apiyi.com).

Hier siehst du die vollständige Konfigurationsansicht für einen Anbieter. Für dich sind nur vier Zeilen wichtig:

Abbildung 4 · Konfigurationsseite des APIYI-Anbieters: Unter Base URL zuerst das Protokoll auswählen und dann die Adresse eintragen, unter Accounts den Key hinterlegen und unter Models die Modelle auswählen, die für Agents verfügbar sein sollen.

Hier wird der zuvor erwähnte Ansatz „ein Token, mehrere Protokolle“ konkret: Die Adresse lautet immer https://api.apiyi.com. Wenn du Anthropic-kompatibel auswählst, erhältst du den nativen Endpunkt für Claude Code. OpenAI-kompatibel ist der /v1-Endpunkt für Codex / Pi / Hermes. Für Gemini gilt dasselbe Prinzip. Du musst also weder drei Anbieter noch drei Keys verwalten.

Speichere die Einstellungen und prüfe in der Anbieterliste zwei Dinge: Auf der Karte wird eine Modellanzahl angezeigt und der Schalter ist aktiviert. Wenn du · N Modelle siehst, funktionieren Key und Adresse – diese Anzeige dient bereits als Selbsttest. Du musst dafür keinen zusätzlichen Befehl ausführen.

✅ Abnahme dieses Schritts: Deine Karte erscheint in der Anbieterliste und zeigt etwas wie · N Modelle statt „Nicht konfiguriert“.

Schritt 4: Die installierten Agents nacheinander verbinden

Wechsle zurück zur Seite Agent und führe für jedes installierte Tool dieselben drei Schritte aus. Auf dieser Seite werden alle Agents aufgeführt, die magpie verbinden kann. Die Liste wird laufend erweitert. Für nicht installierte Tools wird „CLI nicht gefunden“ angezeigt. Verbinde alle Tools, die du installiert hast. Die folgende Tabelle zeigt lediglich die vier gängigsten Beispiele:

1. Den Schalter rechts aktivieren (er wechselt von grau zu hell)
2. Rechts neben dem Schalter ein Modell auswählen (ohne Auswahl wird das Standardmodell verwendet; das gewählte Modell wird in der Konfiguration des jeweiligen Tools gespeichert)
3. Das Tool wie angegeben neu starten (bei Codex, Claude Code, Pi und Hermes muss der Prozess meist neu gestartet werden, damit die neue Konfiguration geladen wird)

Abbildung 5 · Öffne die Modellauswahl: Mit dem ersten Eintrag „Standard“ verwendet der Agent sein eigenes Modell und läuft nicht über magpie. Jeder Eintrag darunter ist mit „über magpie“ gekennzeichnet. Das ausgewählte Modell wird über den entsprechenden vorgelagerten Anbieter genutzt.

An den folgenden Statusmeldungen erkennst du, dass alles in die richtige Richtung läuft:

• Verbunden: Die Konfiguration wurde geschrieben und wird nach einem Neustart des Tools wirksam
• Nicht verbunden · verwendet eigene Einstellungen von XXX: Der Schalter ist nicht aktiviert oder es wurde noch kein Modell ausgewählt
• Kann nur die eigenen Modelle von XXX verwenden; magpie kann nicht verbunden werden: Dieses Tool (zum Beispiel Cursor) lässt nur die Verwendung der eigenen Modelle zu. Das ist eine Einschränkung des Designs und kein Konfigurationsfehler
• CLI nicht gefunden: Das Tool ist nicht installiert oder nicht im PATH verfügbar. Installiere es oder ergänze den PATH und versuche es erneut

💡 Du möchtest für verschiedene Agents unterschiedliche Modelle einrichten – Claude für Claude Code, GPT für Codex und ein günstiges Modell für Hermes? Wähle die Modelle einfach hier jeweils einzeln aus. Das ist einer der wichtigsten Vorteile von magpie gegenüber Skripten, die nur Umgebungsvariablen setzen.

✅ Abnahme dieses Schritts: Die Schalter aller installierten Tools sind aktiviert und in der Statuszeile steht nicht mehr „Nicht verbunden“.

Schritt 5: Jeden Agenten mit einer einfachen Aufgabe testen

Die Konfiguration allein reicht nicht – entscheidend ist, dass alles funktioniert. Senden Sie in jedem Tool eine möglichst einfache Aufgabe:

Am einfachsten prüfen Sie, ob die Anfragen tatsächlich über das Gateway laufen, indem Sie in der APIYI-Konsole die Nutzung und Protokolle dieses Tokens aufrufen. Gibt es neue Aufzeichnungen zu Aufrufen, werden die Anfragen aller Agenten tatsächlich über denselben API-Schlüssel geleitet.

✅ Abnahme für diesen Schritt: Jeder Agent gibt eine normale Antwort zurück, und in der Konsole sind die zugehörigen Aufrufe zu sehen.

Anhang: Welches Modell soll ich wählen? (Standardempfehlungen bei Unsicherheit)

💡 Testen Sie dieselbe Aufgabe am besten jeweils mit verschiedenen Agenten und Modellen. Mit einem einheitlichen API-Schlüssel müssen Sie beim Wechsel nur den Modellnamen ändern – der Kostenvergleich ist also ganz einfach.

Schritt 6 (optional): Welche Konfigurationen magpie für dich anlegt

Dieser Abschnitt ist nicht nötig, damit alles funktioniert. Im Alltag musst du diese Dateien nicht anfassen: Sobald du in Schritt 4 den Schalter aktivierst, hat magpie die folgenden Einstellungen bereits vorgenommen. Hier stehen sie aus zwei Gründen: Damit du im Problemfall weißt, welche Ebene du überprüfen musst, und damit du die Konfiguration direkt übernehmen kannst, falls du magpie irgendwann nicht mehr verwenden möchtest.

Claude Code: ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_BASE_URL="https://api.apiyi.com"   # Nativer Anthropic-Endpunkt
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"
# Optional: Standardmodell festlegen (maßgeblich ist die Modellliste in der Konsole)
# export ANTHROPIC_MODEL="<Claude-Modellname>"
claude

Du kannst die Variablen auch in das Feld env in ~/.claude/settings.json eintragen. Dann sind sie nicht an eine bestimmte Terminalsitzung gebunden.

Codex: Provider-Abschnitt in ~/.codex/config.toml

# ~/.codex/config.toml
model = "<GPT-Modellname>"
model_provider = "apiyi"

[model_providers.apiyi]
name = "APIYI"
base_url = "https://api.apiyi.com/v1"   # OpenAI-kompatibler Endpunkt
env_key = "APIYI_API_KEY"
wire_api = "responses"                   # Wenn das gewählte Modell Responses nicht unterstützt, auf "chat" ändern

Bei wire_api lauert die häufigste Fehlerquelle: Neuere Codex-Versionen verwenden standardmäßig das Responses-Protokoll. Wenn das Modell auf Gateway-Seite nur Chat Completions unterstützt, musst du den Wert auf chat ändern.

Pi und Hermes: Einen benutzerdefinierten OpenAI-kompatiblen Provider einrichten

Das Prinzip ist dasselbe: Als base_url trägst du https://api.apiyi.com/v1 ein und für den Schlüssel verweist du auf APIYI_API_KEY. Die Struktur unterscheidet sich je nach Version. Maßgeblich ist die jeweilige offizielle Dokumentation:

// Pi: Provider in der Konfiguration für benutzerdefinierte Modelle festlegen (die Struktur richtet sich nach der offiziellen Pi-Dokumentation)
{
  "providers": {
    "apiyi": {
      "baseUrl": "https://api.apiyi.com/v1",
      "api": "openai-completions",
      "apiKey": "APIYI_API_KEY",
      "models": [{ "id": "<Modellname>" }]
    }
  }
}

# Hermes: hermes model ausführen und einen benutzerdefinierten OpenAI-kompatiblen Endpunkt auswählen,
# dann die folgenden Angaben eingeben (oder im Hermes-Konfigurationsverzeichnis in .env / config hinterlegen)
#   Base URL : https://api.apiyi.com/v1
#   API Key  : $APIYI_API_KEY
#   Model    : <Modellname>

#!/usr/bin/env bash
# agents-env.sh —— Alternative ohne magpie: Ein Schlüssel für alle Agents
# Verwendung: source agents-env.sh
: "${APIYI_API_KEY:?Bitte zuerst APIYI_API_KEY exportieren}"

# Claude Code (Anthropic-Protokoll)
export ANTHROPIC_BASE_URL="https://api.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"

# Allgemeine Variablen für OpenAI-kompatible Tools wie Codex / Pi / Hermes
export OPENAI_BASE_URL="https://api.apiyi.com/v1"
export OPENAI_API_KEY="$APIYI_API_KEY"

# Verbindung prüfen
curl -s "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $APIYI_API_KEY" | head -c 300 && echo
echo "✅ Alle Agents verwenden jetzt dasselbe Gateway"

curl -s "https://api.apiyi.com/v1/models" \
  -H "Authorization: Bearer sk-dein-token" | head -c 300

Bei Problemen zuerst hier nachsehen: vier häufige Fehlermeldungen

Bei der Fehlersuche gehst du immer von unten nach oben vor: Prüfe zuerst, ob Gateway und Schlüssel funktionieren (wird auf der Provider-Karte · N Modelle angezeigt?), dann die native Konfiguration des jeweiligen Agents und zuletzt die Zuordnungsebene von magpie. So findest du mit drei Prüfungen heraus, ob das Problem beim Upstream, beim Tool selbst oder bei der zentralen Konfiguration liegt.

Häufig gestellte Fragen (FAQ)

Schnellübersicht in fünf Minuten

• Aufgabenteilung: magpie verwaltet die Modellzuordnung, das Gateway die Weiterleitung nach Protokoll – jeder Teil übernimmt genau eine Aufgabe.
• Ein Token: Wählen Sie einen Anbieter, der mehrere Protokolle unterstützt. Dann verwenden alle Agents denselben Schlüssel und eine gemeinsame Abrechnung.
• Reihenfolge beim Einrichten: Token in der Konsole erstellen → unter „Anbieter“ einfügen → Agent-Schalter aktivieren → die Agents nacheinander testen. Alles lässt sich direkt im Fenster erledigen, ohne Befehle.
• Reihenfolge bei der Fehlersuche: Gateway → native Agent-Konfiguration → Zuordnungsebene von magpie. Prüfen Sie die Ebenen von unten nach oben.
• Wichtig für Claude Code: ANTHROPIC_AUTH_TOKEN verwenden und bei base_url kein /v1 anhängen.
• Wichtig für Codex: wire_api muss mit dem vom Modell unterstützten Protokoll übereinstimmen.
• Alternative: Mit einem Skript für Umgebungsvariablen (agents-env.sh) können ebenfalls alle Agents denselben Schlüssel verwenden.

Wenn Sie mehr als drei Agents verwenden, lohnt es sich, eine halbe Stunde in diese Konfiguration zu investieren. Danach müssen Sie beim Modellwechsel oder beim Austausch des Schlüssels nur noch eine Stelle ändern. Über APIYI auf apiyi.com können Sie Testguthaben erhalten. Damit lassen sich zunächst die wichtigsten Tools einrichten und anschließend die Modelle für die einzelnen Agents je nach Aufgabe genauer zuweisen.

Weiterlesen: Verwandte Artikel

• 📘 Unterstützt Workbuddy Aufrufe im nativen Claude-Format? 3 Hauptgründe und praktische Fehleranalyse für 6 Arten von content-Fehlern: In diesem Artikel erfahren Sie, worin sich das native Anthropic-Format und das OpenAI-kompatible Format unterscheiden. Auch der Grund für Schritt 2 dieses Artikels – „Claude Code muss den nativen Endpunkt verwenden“ – wird dort erklärt.
• 📊 claude-sonnet-5-5 vs. claude-opus-5-5: Ist Opus schneller und Sonnet nur noch günstiger? 6 Datensätze zeigen die beste Kombination für Agents mit großem Kontextfenster in Unternehmen: Lesen Sie diesen Artikel, bevor Sie in Schritt 4 verschiedenen Agents Modelle zuweisen. So können Sie entscheiden, wer Opus und wer ein günstigeres Modell verwenden sollte.
• ⚠️ Wie viele gleichzeitige Anfragen unterstützt gemini-4-argon in AI Studio? 5 Gründe für häufige 429-Fehler und 6 Schritte zur Lösung: Wenn mehrere Agents gleichzeitig denselben API-Schlüssel nutzen und an ein Rate-Limit stoßen, helfen die sechs Schritte in diesem Artikel bei der Fehlersuche.
• 🧭 OpenAI-Fehler „model not found“? GPT-5.5 wurde am 14. Oktober aus ChatGPT entfernt: 5 Schritte zur Fehlersuche und Alternativen: Wenn bei der Überprüfung in Schritt 5 die Meldung „Modell nicht gefunden“ erscheint, prüfen Sie zuerst, ob der Modellname noch gültig ist.

📚 Referenzen

1. GitHub – magpie: offizielles Projekt-Repository
2. Link: github.com/yetone/magpie
3. Hinweis: Maßgeblich für Installation, Konfigurationsformat und Versionsupdates ist die README.
4. Offizielle Dokumentation zu Claude Code: Umgebungsvariablen und Einstellungen
5. Link: docs.anthropic.com/en/docs/claude-code
6. Hinweis: Offizielle Informationen zu Variablen wie ANTHROPIC_BASE_URL
7. Repository von OpenAI Codex CLI: Konfiguration mit config.toml und model_providers
8. Link: github.com/openai/codex
9. Hinweis: Informationen zu benutzerdefinierten Providern und zum Parameter wire_api
10. APIYI-Dokumentation: Endpunkte für mehrere Protokolle und Modellliste
11. Link: docs.apiyi.com
12. Hinweis: Informationen zur Anbindung von Endpunkten für Protokolle wie OpenAI und Anthropic

Autor: Technisches Team von APIYI
Technischer Austausch: Teilen Sie Ihre Erfahrungen mit magpie-Konfigurationen gerne in den Kommentaren. Weitere Informationen zur Anbindung finden Sie im Dokumentationszentrum von APIYI unter docs.apiyi.com.