Pi installieren und OmniProxy konfigurieren

Pi ist ein kleiner Terminal-Assistent – ein Programm, das direkt in der Befehlszeile mit Ihnen spricht, Dateien liest und Aufgaben erledigt. Es hat einen kurzen System-Prompt und standardmäßig nur wenige Tools. Wenn Sie andere Befehle, Workflows oder Schnittstellen benötigen, können Sie diese später über Erweiterungen hinzufügen. Erweiterungen sind Komponenten, die Pi Funktionen hinzufügen, und Sie können sie nach der Erstellung mit anderen teilen.

Unteragenten delegieren einen Teil einer Aufgabe an einen anderen Assistenten, während der Planungsmodus die Schritte organisiert, bevor die Ausführung beginnt. Keine dieser Funktionen ist standardmäßig enthalten, aber Sie können Pi bitten, sie zu erstellen oder von anderen geteilte Pakete zu installieren.

Vorbereitung

macOS und Linux verwenden ein Installationsskript – einen einzigen Befehl, der Pi automatisch herunterlädt und installiert. Verwenden Sie unter Windows den PowerShell-Befehl, der auf der Pi-Homepage bereitgestellt wird. PowerShell ist die Befehlszeilenumgebung, die in Windows enthalten ist. Sie können Pi auch in WSL installieren, der Linux-Umgebung, die in Windows verfügbar ist.

Wenn Sie sich für die Installation mit npm entscheiden, benötigen Sie Node.js 22.19 oder neuer. npm ist der Paketmanager, der mit Node.js verwendet wird und Pi über die Befehlszeile installieren kann.

macOS Linux

install.sh

• curl das offizielle Skript
• Der Installer fixiert die Abhängigkeiten
• Aktualisieren mit pi update

Windows

install.ps1

• Offizieller PowerShell-Befehl
• Git for Windows bietet Bash
• Sie können auch WSL verwenden

Node bereits installiert

npm

• Erfordert Node 22.19+
• Der Paketname ist pi-coding-agent
• Fügen Sie --ignore-scripts hinzu

Pi installieren und zum ersten Mal starten

Öffnen Sie unter macOS oder Linux ein Terminal und führen Sie aus:

curl -fsSL https://pi.dev/install.sh | sh

Öffnen Sie unter Windows PowerShell und führen Sie aus:

powershell -c "irm https://pi.dev/install.ps1 | iex"

Wenn Node.js 22.19 oder neuer bereits installiert ist, können Sie auch den alternativen Befehl aus dem Quickstart verwenden:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Das Installationsskript kann pausieren, um Fragen in einem interaktiven Terminal zu stellen. Folgen Sie den Anweisungen auf dem Bildschirm, um fortzufahren. Wenn Sie bereits eine kompatible Version von Node haben, stellt dieser npm-Befehl keine Fragen. Um Pi in einem anderen Verzeichnis zu installieren, fügen Sie --prefix /your/directoryhinzu. Am 09.10.2026 wurde damit Pi 1.1.0 installiert.

Eine normale npm-Installation erfordert keine Abhängigkeits-Lebenszyklus-Skripte, das sind Skripte, die Pakete während der Installation automatisch ausführen. Das Installationsskript fixiert Abhängigkeiten; aktualisieren Sie Pi danach mit pi update. Verwenden Sie für eine npm-Installation die von Ihrem Paketmanager bereitgestellte Update-Methode. Nix-Benutzer sollten von Pis Flake installieren. Ein Flake ist eine Nix-Konfiguration, die Software und ihre Abhängigkeiten beschreibt, und pi update kann eine Nix-Installation nicht aktualisieren.

Bestätigen Sie nach der Installation zuerst, dass Ihr Terminal Pi finden kann:

pi --version

Wenn Sie unter Windows möchten, dass Modelle Bash-Befehle ausführen, wird die Installation von Git for Windows für die meisten lokalen Benutzer empfohlen. Bash ist die Befehlsumgebung, die Pi verwendet, um einige Befehle auszuführen. Pi überprüft die shellPath Einstellung in ~/.pi/agent/settings.json, Git Bash unter Program Files und dann bash.exe auf PATH, in dieser Reihenfolge. shellPath gibt den Speicherort von Bash an, während PATH die Liste der Verzeichnisse ist, die das System nach Befehlen durchsucht.

Nach dem Start von Pi können Sie !printf 'Bash is working\n' eingeben, um es zu überprüfen. Wenn sich Ihre Dateien und Tools bereits in WSL befinden, installieren Sie Pi in dieser Linux-Umgebung, indem Sie dem Quickstart folgen.

Gehen Sie als Nächstes in den Ordner, den Pi untersuchen oder bearbeiten soll, und starten Sie es dann:

cd /path/to/folder
pi

Dieser Ordner wird zum aktuellen Arbeitsbereich von Pi. Pi verwendet ihn, um Dateien und Konfigurationen zu entdecken und Sitzungen zu gruppieren.

Verbindungswerte von OmniProxy abrufen

Erhalten Sie zuerst diese drei Werte von OmniProxy:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy the full ID from the current OmniProxy model list

baseUrl ist der API-Endpunkt, an den Pi Anfragen sendet; die Adresse muss /v1 enthalten. apiKey ist der Schlüssel für den API-Zugriff. Model ID ist der Name des aufzurufenden Modells und muss vollständig aus der aktuellen OmniProxy-Modellliste kopiert werden.

Setzen Sie api auf openai-completions, wie im Beispiel für die kompatible API gezeigt. Dieses Feld teilt Pi mit, welches API-Format beim Senden von Anfragen verwendet werden soll.

Kopieren Sie die gesamte Modell-ID, einschließlich aller Schrägstriche im Namen. Am 09.10.2026 waren die beiden Referenz-IDs in der Anbieterdokumentation gemini-3.8-flash und grok-4.7. Kopieren Sie keinen Namen, der nicht in der Liste vorhanden ist.

Tool-Konfiguration eingeben

Die benutzerdefinierte Modellkonfiguration von Pi auf Benutzerebene wird in models.jsongespeichert. Diese Datei befindet sich im Agentenverzeichnis, das standardmäßig ~/.pi/agentist, also ist ihr vollständiger Pfad ~/.pi/agent/models.json. Wenn die PI_CODING_AGENT_DIR Umgebungsvariable festgelegt ist, verwendet Pi stattdessen das durch diese Variable angegebene Verzeichnis. Eine Umgebungsvariable ist ein Konfigurationswert, der vom System bereitgestellt wird, damit Programme ihn lesen können.

Geben Sie die Konfiguration wie im Beispiel für die kompatible API gezeigt ein:

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

providers listet die verbundenen Dienste auf, während models die Modelle auflistet, die ausgewählt werden können. Jedes Modell id muss mit der vollständigen Modell-ID in der aktuellen OmniProxy-Modellliste übereinstimmen. input gibt an, dass das Modell hier für die Texteingabe konfiguriert ist.

apiKey kann als literaler Wert eingegeben werden oder als $NAME oder ${NAME} damit Pi ihn aus einer Umgebungsvariable liest. Ein Wert, der mit ! beginnt, wird als Befehl behandelt und für jede Anfrage ausgeführt. Übertragen Sie keinen echten Schlüssel in ein Repository. Wenn das Gateway keine Schlüssel validiert, können Sie eine Platzhalter-Zeichenfolge eingeben, die nur auf Ihrem lokalen Computer verwendet wird. Am 09.10.2026 hat Pi die Datei mit dieser Konfiguration erfolgreich gelesen.

Das Öffnen von /model lädt diese Datei neu. /model ist die Schnittstelle in Pi zum Anzeigen und Auswählen von Modellen. Benutzerdefinierte Modelle erscheinen nicht in /model bis Pi ihre Anmeldedaten auflösen kann. Drücken Sie nach der Auswahl eines Modells Ctrl+S um es als Standardmodell für neue Sitzungen zu speichern.

Datei

models.json

• Standardverzeichnis: ~/.pi/agent
• Fügen Sie einen Eintrag unter providers hinzu
• Setzen Sie api auf completions

Adresse

baseUrl

• Fügen Sie /v1 hinzu
• apiKey kann auf eine Variable verweisen
• Die Modell-ID muss exakt sein

Auswählen

/model

• Das Öffnen lädt die Datei neu
• Wählen Sie das Modell aus, das Sie gerade hinzugefügt haben
• Strg+S speichert es als Standard

Mit einer echten Aufgabe verifizieren

Nach Abschluss der Konfiguration können Sie eine nicht-interaktive Prüfung in einem Verzeichnis durchführen, das Dateien enthält. Nicht-interaktiver Modus bedeutet, dass Pi diese einzelne Aufgabe abschließt und dann beendet, anstatt eine laufende Unterhaltung zu führen. Ersetzen Sie den Wert nach --model durch die vollständige ID aus der aktuellen OmniProxy-Liste:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Read the first line of the file you specify. Do not modify the file."

Hier --tools read aktiviert nur das Lese-Tool, und die Aufgabe weist Pi auch explizit an, die Datei nicht zu ändern. Am 09.10.2026 hat Pi 1.1.0 den Dateiinhalt erfolgreich gelesen. Die erste Antwort dauerte etwa zwei Minuten.

Sie können auch den interaktiven Modus verwenden: Gehen Sie in das Verzeichnis, führen Sie piaus und wählen Sie dann ein Modell mit /model. Eine Beispielaufgabe im Quickstart bittet Pi zu erklären, wie das Repository organisiert ist und wie man seine Prüfungen ausführt. Beobachten Sie, ob es die Dateien liest und eine Erklärung liefert, und bestätigen Sie dann die Quelle und die Modell-ID in den Anfrageprotokollen von OmniProxy.

Starten

pi startet

• Zuerst cd in den Ordner
• pi --version erzeugt eine Ausgabe
• Der Modellname erscheint am unteren Rand der Schnittstelle

Aufgabe

Es hat das Verzeichnis gelesen

• Fragen Sie, wie das Repository organisiert ist
• Überprüfen Sie die Dateien, die es auflistet
• Verlassen Sie sich nicht nur auf ein erfolgreiches Speichern der Konfiguration

Protokolle

Sichtbar im Gateway

• Quelle ist Pi
• Modell-ID stimmt überein
• Behalten Sie den Schlüssel auf dem lokalen Computer

Häufige Fehler

• pi kann nicht gefunden werden: Öffnen Sie das Terminal erneut und versuchen Sie es erneut mit pi --version . Bestätigen Sie bei einer npm-Installation, dass sich das globale bin-Verzeichnis auf PATH befindet.
• Die benutzerdefinierten Modelle erscheinen nicht in /model: Bestätigen Sie, dass models.json in ~/.pi/agent/ist, überprüfen Sie, dass apiKey aufgelöst werden kann, und öffnen Sie dann erneut /model.
• Windows meldet, dass Bash nicht gefunden werden kann: Installieren Sie Git for Windows oder setzen Sie shellPath in ~/.pi/agent/settings.json. Backslashes in JSON müssen zweimal geschrieben werden.
• Die Anfrage wird abgelehnt: Überprüfen Sie, dass api ist openai-completions und dass baseUrl mit /v1endet. Aktivieren Sie keine zusätzlichen Kompatibilitätsoptionen nur deshalb, weil sich der Dienst als kompatibel beschreibt.
• Die Modell-ID ist ungültig: Kopieren Sie sie erneut aus der aktuellen OmniProxy-Liste.

Offizielle Referenzen

Für Installationsbefehle siehe die Pi website und Quickstart. Für die Modelldatei siehe Choose a Model und Configuration. Für die Windows-Befehlsumgebung siehe Run Pi on Windows. Für die in den Beispielen verwendeten Modell-IDs siehe Gemini model list und xAI models page.

Ersetzen Sie jeden Platzhalter mit Werten aus Ihrer eigenen OmniProxy-Konfiguration. Veröffentlichen Sie niemals einen echten Schlüssel.

Ein gespeicherter HTTP 200 allein beweist keine vollständige Agenten-Kompatibilität. Überprüfen Sie die Quelle und das Modell im Aufrufprotokoll von OmniProxy.

Offizielle Quellen · Pi ↗