Pi-Coding-Agent-Modellkonfiguration: /login, models.json und benutzerdefinierter Provider

Die Modellkonfiguration des Pi-Coding-Agents ist in drei Ebenen aufgeteilt: Bei integrierten Providern meldest du dich mit /login an (Abonnement oder API-Schlüssel) oder setzt eine Umgebungsvariable; Endpunkte, die nicht integriert, aber mit der OpenAI-, Anthropic- oder Google-API kompatibel sind, trägst du in ~/.pi/agent/models.json ein; nur Dienste mit spezieller Authentifizierung oder speziellen Protokollen benötigen eine Erweiterung. Nach der Auswahl wechselst du mit /model.Dieser Artikel erläutert anhand der nach der Überarbeitung vom 22. September 2026 aktualisierten Pi-Dokumentation und des am 30. September 2026 veröffentlichten Quellcodes von v0.99.2, wie jede Ebene konfiguriert wird, in welcher Reihenfolge Schlüssel gelesen werden (das hat sich nach der Überarbeitung geändert), welche drei Standardwerte bei benutzerdefinierten Modellen unbemerkt Fehler verursachen können und wie du einen OpenAI-kompatiblen Endpunkt vollständig einbindest.

Prüfe zuerst, um welches Pi es geht. Diese Seite behandelt den von Earendil unter pi.dev veröffentlichten terminalbasierten Coding-Agent, dessen Repository earendil-works/pi (früher badlogic/pi-mono) ist und der unter der MIT-Lizenz steht. Es handelt sich nicht um Inflections Chatbot Pi (pi.ai), die Pi-Network-Währung, Raspberry Pi oder das Oh My Pi eines anderen Autors.

Verbindungsart auswählen

Am Anfang der Modelldokumentation von Pi steht genau diese Übersicht:

Pi enthält einen Modellkatalog und kann aktuellere Katalogdaten von pi.dev ergänzen; offline wird der Cache weiterverwendet. Für eine erzwungene Aktualisierung kannst du pi update --models ausführen. Eine benutzerdefinierte Modellkonfiguration ist nur erforderlich, wenn Pi den benötigten Provider oder Endpunkt nicht kennt.

Modell in Pi auswählen

• /model: Modelle suchen und auswählen. Angezeigt werden nur Modelle, für deren Provider bereits eine verwendbare Authentifizierung vorhanden ist.
• Auf einem Modell Ctrl+S drücken: Als Standardmodell für neue Sitzungen speichern.
• /thinking: Die Denkstufe des aktuellen Modells auswählen. Pi zeigt nur die vom Modell unterstützten Stufen an; mit Ctrl+S wird sie ebenfalls als Startstandard gespeichert.
• Ctrl+P: Zwischen verfügbaren Modellen wechseln; mit /scoped-models die Wechselliste verwalten und speichern.

Die Sitzung zeichnet Änderungen an Modell und Denkstufe auf und stellt sie beim Wiederaufnehmen der Sitzung entsprechend wieder her, ändert jedoch nicht die Standards für neue Sitzungen.

Reihenfolge beim Lesen der Schlüssel (nach der Überarbeitung geändert)

Wenn mehrere Schlüsselquellen gleichzeitig konfiguriert sind, gilt laut Pi-Dokumentation folgende Reihenfolge: --api-key zur Laufzeit → in auth.json gespeicherte Anmeldedaten → models.json mit apiKey → Umgebungsvariable des Providers (oder Anmeldedaten der Cloud-Plattform). Ein alter Schlüssel, der mit /login gespeichert wurde, überschreibt daher den Schlüssel, den du gerade in die Datei geschrieben hast. Das ist der häufigste Grund dafür, dass trotz geänderter Konfiguration weiterhin das alte Konto verwendet wird; mit /logout kannst du gespeicherte Anmeldedaten entfernen. Beachte: Vor der Überarbeitung am 22. September stand in der Dokumentation die Umgebungsvariable vor models.json. Ältere Anleitungen im Internet können daher noch die alte Reihenfolge beschreiben.

Ein weiteres häufiges Missverständnis: Wenn ein Modell nicht in /model erscheint, liegt das meist an der Authentifizierung und nicht an einem fehlerhaften JSON. Die Dokumentation sagt, dass benutzerdefinierte Modelle aus models.json geladen werden können; bis Pi die Anmeldedaten auflösen kann, bleiben sie jedoch „nicht verfügbar“.

models.json: vollständiges Beispiel für einen OpenAI-kompatiblen Endpunkt

Das eigene Beispiel von Pi verwendet lokales Ollama – der Dummy-Schlüssel macht das Modell lediglich verfügbar; Ollama selbst prüft ihn nicht:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [{ "id": "qwen2.5-coder:7b" }]
    }
  }
}

Ein Endpunkt, der Authentifizierung benötigt, etwa Kunavo, wird so angebunden:

{
  "providers": {
    "kunavo": {
      "baseUrl": "https://api.kunavo.com/v1",
      "api": "openai-completions",
      "apiKey": "$KUNAVO_API_KEY",
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "Claude Sonnet 5",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1000000,
          "maxTokens": 128000
        },
        {
          "id": "claude-haiku-4-5",
          "name": "Claude Haiku 4.5",
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 64000
        }
      ]
    }
  }
}

• baseUrl und api sind erforderlich.Sie können auf Provider- oder Modellebene eingetragen werden; laut Quellcode von v0.99.2 lädt Pi das Modell nicht, wenn einer der beiden Werte fehlt.
• api ist keine Auswahl aus vier Möglichkeiten.Vor der Überarbeitung am 22. September führte die Pi-Dokumentation für benutzerdefinierte Provider vier Werte auf: openai-completions, openai-responses, anthropic-messages und google-generative-ai. In der überarbeiteten Dokumentation fehlt diese Liste; in der obigen Übersicht steht nur „OpenAI-, Anthropic- oder Google-kompatible Endpunkte“, und das Beispiel verwendet ebenfalls nur openai-completions. Der Quellcode von v0.99.2 definiert api als beliebige Zeichenfolge und übergibt sie an die entsprechende von zehn integrierten Implementierungen – die vier genannten sowie openai-codex-responses, azure-openai-responses, google-vertex, mistral-conversations, bedrock-converse-stream und pi-messages. Nur die ersten vier wurden in der Dokumentation als Verwendung für benutzerdefinierte Provider beschrieben; die anderen sechs wurden hier nicht getestet, und diese Seite behauptet nicht, dass sie Drittanbieter-Endpunkte anbinden können.
• Die baseUrl von openai-completions muss /v1 enthalten.Die Dokumentation schreibt diese Regel nicht in einem einzigen Satz vor, aber alle Beispiele für kompatible Endpunkte enthalten einen Versionspfad. Ohne /v1 erhältst du 404 statt eines Authentifizierungsfehlers.
• Schlüssel nicht fest eintragen.apiKey und Header-Werte können mit $NAME oder ${NAME} auf Umgebungsvariablen verweisen, direkt als Wert eingetragen oder mit !指令 abgerufen werden; laut Dokumentation werden die Befehle in models.json bei jeder Anfrage ausgeführt und nicht zwischengespeichert. Behandle auth.json und alle Befehle zum Abrufen von Schlüsseln vertraulich.
• Nach Änderungen ist kein Neustart erforderlich.Beim Öffnen von /model wird die Datei erneut gelesen. Ein Eintrag mit derselben ID in models fügt das Modell des Providers hinzu oder ersetzt es; wenn du Metadaten eines integrierten Modells ändern möchtest, ohne den gesamten Katalog zu ersetzen, verwende modelOverrides.

Drei Standardwerte, die unbemerkt Fehler verursachen

Bei der Überarbeitung der Dokumentation am 22. September wurde die Feldtabelle entfernt, die Standardwerte stehen jedoch weiterhin im Quellcode (in provider-composer.ts von v0.99.2). Bei benutzerdefinierten Modellen werden fehlende Werte wie folgt gesetzt:

Außerdem ist reasoning standardmäßig false, und input unterstützt standardmäßig nur Text. Das Kunavo-Beispiel oben enthält Kontext- und Ausgabelimits gemäß der Preisliste, verwendet aber kein cost, weil fest im Code hinterlegte Preise schnell veralten – wenn unten Kosten angezeigt werden sollen, trage die Preise pro einer Million Token selbst gemäß der Preisliste ein. Pi unterstützt außerdem promptCache (damit wird die Lebensdauer des Anbieter-Caches in Sekunden angegeben, um den Cache aufzuwärmen); die Dokumentation empfiehlt den konservativeren Wert aus dem öffentlich verfügbaren Bereich.

anthropic-messages: Anbindung möglich, aber baseUrl nicht eindeutig

anthropic-messages ist einer der vier Werte, die die frühere Dokumentation für benutzerdefinierte Provider aufführte, und Kunavo bietet ebenfalls eine Anthropic-Messages-Schnittstelle. Daher ist der Weg über api: "anthropic-messages" grundsätzlich möglich. Die Pi-Dokumentation hat jedoch nie eindeutig erklärt, ob die baseUrl dieses Typs /v1 enthalten muss: Ein früheres Beispiel verwendet https://proxy.example.com/v1, ein anderes https://proxy.example.com ohne Pfad; nach der Überarbeitung wurde der Pfad aus beiden Beispielen entfernt, ohne eine eindeutige Regel zu nennen. Wenn du diesen Weg verwendest, probiere zunächst eine Variante. Liefert die erste Anfrage 404 (nicht 401), ändere diese Zeile. In compat gibt es außerdem einige Schalter, die speziell für nicht originale Endpunkte vorgesehen sind (zum Beispiel supportsEagerToolInputStreaming und supportsStrictTools). Die Dokumentation weist jedoch darauf hin, dass eine Kompatibilitätskonfiguration „verifizierte Verhaltensunterschiede“ beschreiben sollte und nicht allein deshalb aktiviert werden darf, weil ein Endpunkt OpenAI- oder Anthropic-Kompatibilität behauptet. Das Beispiel für openai-completions oben umgeht diese Probleme. Das ist der eigentliche Grund, warum es als Ausgangspunkt empfohlen wird, nicht weil es schneller wäre.

Offene Angaben und Bezahlung

Die obigen Angaben sind eine aus der Pi-Dokumentation und dem Quellcode zusammengestellte Konfigurationsreferenz. Kunavo hat den eigenen Endpunkt nicht praktisch mit Pi ausgeführt – weder Sitzungen, Streaming oder Tool-Aufrufe getestet noch bestätigt, bei welchem Modell die Anfrage letztlich landet. Behalte den derzeit funktionierenden Weg bei und gib Pi testweise eine Aufgabe, die echte Dateien liest und schreibt. Da Pi fast jeden Schritt über Tool-Aufrufe ausführt, zeigt ein solcher erster Lauf Probleme mit Streaming oder dem Tool-Format am ehesten. Die vollständige englische Konfigurationsseite findest du im Pi integration guide; einen Vergleich der kostenpflichtigen Wege (einschließlich des Radius-Gateways von Earendil) bietet Pi coding agent pricing.

Kunavo ist ein Prepaid-Guthaben mit tokenbasierter Abrechnung ohne monatliche Gebühren. Die Mindestaufladung beträgt $10; der Checkout läuft über Stripe. In Taiwan können Kreditkarten (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay und Link verwendet werden; JkoPay und LINE Pay stehen nicht zur Verfügung. Weitere Informationen finden Sie in der Abrechnungsdokumentation. Danach können Sie ein Konto erstellen und einen Schlüssel erzeugen.

Häufig gestellte Fragen

Geprüft am 1. Oktober 2026: die Seiten pi.dev/docs/latest/models (Choose a Model) und providers, der Tag v0.99.2 von earendil-works/pi mit src/core/model-config.ts und provider-composer.ts sowie Versionsinformationen der GitHub API. Am selben Tag wurde das Feld api zusätzlich geprüft: welche Werte die models-Seite derzeit aufführt (nur openai-completions im Ollama-Beispiel), der Typ von api in model-config.ts von v0.99.2 (beliebige Zeichenfolge, Zeilen 191 und 233), die Zuordnung benutzerdefinierter Modelle in provider-composer.ts (Zeile 579) sowie BUILTIN_APIS in packages/ai/src/compat.ts (Zeile 180, insgesamt zehn Werte). Kunavo hat den eigenen Endpunkt nicht praktisch mit Pi ausgeführt.