Pi installieren und mit OmniProxy konfigurieren

Pi ist ein sehr kompakter Terminal-Assistent, also ein Programm, mit dem du direkt über die Kommandozeile sprechen, Dateien lesen und Aufgaben erledigen kannst. Sein System-Prompt ist kurz und die standardmäßig verfügbaren Werkzeuge sind überschaubar. Benötigst du weitere Befehle, Abläufe oder Oberflächen, kannst du sie später über Erweiterungen ergänzen. Erweiterungen sind Komponenten, die Pi zusätzliche Fähigkeiten verleihen und nach ihrer Fertigstellung auch mit anderen geteilt werden können.

Subagenten übertragen einen Teil einer Aufgabe an einen anderen Assistenten. Im Planungsmodus werden dagegen zunächst die Arbeitsschritte ausgearbeitet, bevor die Ausführung beginnt. Beides gehört nicht zum Standardumfang. Du kannst Pi diese Funktionen selbst erstellen lassen oder ein von anderen bereitgestelltes Paket installieren.

Vorbereitung der Installation

Unter macOS und Linux verwendest du ein Installationsskript, also einen einzelnen Befehl, der Download und Installation automatisch ausführt. Unter Windows verwendest du den PowerShell-Befehl von der Pi-Startseite. PowerShell ist die in Windows integrierte Kommandozeilenumgebung. Alternativ kannst du Pi in WSL installieren, der Linux-Umgebung unter Windows.

Wenn du Pi über npm installierst, benötigst du zunächst Node.js 22.19 oder neuer. npm ist der mit Node.js verwendete Paketmanager, über den du Pi von der Kommandozeile aus installieren kannst.

macOS Linux

install.sh

• Offizielles Skript mit curl abrufen
• Abhängigkeiten werden vom Installationsprogramm festgelegt
• Mit pi update aktualisieren

Windows

install.ps1

• PowerShell-Befehl von der offiziellen Website
• Git for Windows stellt Bash bereit
• Alternativ WSL verwenden

Node bereits vorhanden

npm

• Node 22.19+ erforderlich
• Paketname ist pi-coding-agent
• --ignore-scripts hinzufügen

Installieren und erstmals starten

Öffne unter macOS oder Linux ein Terminal und führe Folgendes aus:

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

Öffne unter Windows PowerShell und führe anschließend Folgendes aus:

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

Wenn Node.js 22.19 oder neuer bereits installiert ist, kannst du auch den alternativen Befehl aus dem Quickstart verwenden:

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

In einem interaktiven Terminal kann das Installationsskript anhalten und Fragen stellen. Fahre dann entsprechend den angezeigten Anweisungen fort. Wenn bereits eine geeignete Node-Version vorhanden ist, stellt dieser npm-Befehl keine Fragen. Möchtest du die Installation in einem anderen Verzeichnis ablegen, füge --prefix /dein/verzeichnis hinzu. Am 2026-10-09 wurde auf diese Weise Pi 1.1.0 installiert.

Für eine reguläre npm-Installation sind keine Lifecycle-Skripte der Abhängigkeiten erforderlich, also Skripte, die Pakete während der Installation automatisch ausführen. Das Installationsskript fixiert die Abhängigkeiten; spätere Aktualisierungen erfolgen mit pi update. Bei einer npm-Installation richtet sich die Aktualisierungsmethode nach dem verwendeten Paketmanager. Nix-Benutzer installieren Pi über dessen Flake. Ein Flake ist eine Nix-Konfiguration zur Beschreibung von Software und Abhängigkeiten. Eine Nix-Installation kann nicht mit pi update aktualisiert werden.

Prüfe nach Abschluss der Installation zunächst, ob Pi im Terminal gefunden wird:

pi --version

Wenn das Modell unter Windows Bash-Befehle ausführen soll, empfiehlt sich für die meisten lokalen Installationen Git for Windows. Bash ist die Befehlsumgebung, in der Pi bestimmte Befehle ausführt. Pi sucht der Reihe nach nach shellPath in ~/.pi/agent/settings.json, nach Git Bash unter Program Files und nach bash.exe im PATH. Mit shellPath wird der Speicherort von Bash angegeben. PATH ist die Liste der Verzeichnisse, in denen das System nach Befehlen sucht.

Nach dem Start kannst du mit !printf 'Bash is working\n' prüfen, ob Bash funktioniert. Wenn sich deine Dateien und Werkzeuge bereits in WSL befinden, installiere Pi dort in der Linux-Umgebung gemäß dem Quickstart.

Wechsle anschließend in den Ordner, den Pi untersuchen oder bearbeiten soll, und starte Pi:

cd /path/to/folder
pi

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

Verbindungsparameter aus OmniProxy abrufen

Bereite zunächst die folgenden drei Angaben in OmniProxy vor:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Vollständige ID aus der aktuellen Modellliste von OmniProxy kopieren

baseUrl ist die API-Adresse, an die Pi Anfragen sendet. Sie muss bis einschließlich /v1 angegeben werden. apiKey ist der Schlüssel für den Zugriff auf die API. Model ID bezeichnet den Namen des aufzurufenden Modells und muss vollständig aus der aktuellen Modellliste von OmniProxy kopiert werden.

Trage für api den Wert openai-completions aus dem Beispiel für kompatible APIs ein. Dieses Feld legt fest, in welchem API-Format Pi Anfragen sendet.

Kopiere die Modell-ID vollständig und behalte auch alle Schrägstriche im Namen bei. Am 2026-10-09 waren gemini-3.8-flash und grok-4.7 zwei Vergleichs-IDs aus der Dokumentation der Anbieter. Übernimm keine Namen, die nicht in der Liste enthalten sind.

Werkzeugkonfiguration eintragen

Die benutzerspezifische Konfiguration eigener Modelle für Pi wird in models.json gespeichert. Diese Datei befindet sich im agent-Verzeichnis, das standardmäßig ~/.pi/agent ist. Der vollständige Pfad lautet daher ~/.pi/agent/models.json. Wenn die Umgebungsvariable PI_CODING_AGENT_DIR gesetzt ist, verwendet Pi stattdessen das darin angegebene Verzeichnis. Eine Umgebungsvariable ist ein Konfigurationswert, den das System einem Programm zum Auslesen bereitstellt.

Trage die Werte entsprechend dem Beispiel für kompatible APIs 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"] }
      ]
    }
  }
}

Unter providers werden die eingebundenen Dienste aufgeführt, unter models die auswählbaren Modelle. Die id jedes Modells muss der vollständigen Model ID aus der aktuellen Modellliste von OmniProxy entsprechen. input gibt hier an, dass Texteingaben konfiguriert sind.

Du kannst für apiKey einen literalen Wert oder $NAME beziehungsweise ${NAME} angeben, damit Pi den Schlüssel aus einer Umgebungsvariable liest. Werte, die mit ! beginnen, werden als Befehle behandelt und bei jeder Anfrage ausgeführt. Übertrage keine echten Schlüssel in ein Repository. Wenn das Gateway den Schlüssel nicht überprüft, kannst du eine nur lokal verwendete Platzhalterzeichenfolge eintragen. Am 2026-10-09 konnte die Datei auf diese Weise eingelesen werden.

Beim Öffnen von /model wird diese Datei neu geladen. /model ist in Pi der Einstiegspunkt zum Anzeigen und Auswählen von Modellen. Benutzerdefinierte Modelle erscheinen erst dann unter /model, wenn Pi die Zugangsdaten auswerten kann. Nachdem du ein Modell ausgewählt hast, kannst du es mit Ctrl+S als Standardmodell für neue Sitzungen speichern.

Datei

models.json

• Standardverzeichnis ~/.pi/agent
• Unter providers einen Eintrag hinzufügen
• Für api completions verwenden

Adresse

baseUrl

• Bis einschließlich /v1 angeben
• Für apiKey kann eine Variable angegeben werden
• Modell-id muss exakt sein

Auswahl

/model

• Beim Öffnen wird die Datei neu geladen
• Das soeben hinzugefügte Modell auswählen
• Mit Ctrl+S als Standard speichern

Eine echte Aufgabe überprüfen

Nach Abschluss der Konfiguration kannst du in einem Verzeichnis mit Dateien eine nicht interaktive Prüfung durchführen. Nicht interaktiv bedeutet, dass keine fortlaufende Unterhaltung gestartet wird. Pi beendet sich, nachdem diese eine Aufgabe abgeschlossen wurde. Ersetze den Wert hinter --model durch die vollständige ID aus der aktuellen Modellliste von OmniProxy:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Lies die erste Zeile der von dir angegebenen Datei und ändere die Datei nicht."

Mit --tools read wird ausschließlich das Lesewerkzeug freigegeben. Die Aufgabenbeschreibung verlangt ebenfalls ausdrücklich, dass die Datei nicht geändert wird. Am 2026-10-09 wurde der Dateiinhalt mit Pi 1.1.0 ausgelesen. Die erste Antwort dauerte ungefähr zwei Minuten.

Du kannst auch den interaktiven Modus verwenden: Wechsle in das Verzeichnis, führe pi aus und wähle anschließend mit /model ein Modell aus. Eine Beispielaufgabe aus dem Quickstart besteht darin, Pi erklären zu lassen, wie das Repository organisiert ist und wie die Prüfungen ausgeführt werden. Beobachte, ob Pi die Dateien liest und eine Erklärung liefert. Prüfe anschließend in den Aufrufprotokollen von OmniProxy die Quelle und die Modell-ID.

Start

pi lässt sich öffnen

• Zuerst mit cd zum Ordner wechseln
• pi --version gibt etwas aus
• Modellname wird unten in der Oberfläche angezeigt

Aufgabe

Verzeichnis wurde gelesen

• Nach der Struktur des Repositorys fragen
• Aufgelistete Dateien prüfen
• Nicht nur auf die gespeicherte Konfiguration achten

Protokoll

Im Gateway sichtbar

• Quelle ist Pi
• Modell-ID stimmt überein
• Schlüssel bleibt lokal

Häufige Fehler

• pi wird nicht gefunden: Öffne das Terminal erneut und versuche noch einmal pi --version. Prüfe bei einer npm-Installation, ob sich das globale bin-Verzeichnis im PATH befindet.
• Das benutzerdefinierte Modell fehlt unter /model: Prüfe, ob sich models.json in ~/.pi/agent/ befindet und apiKey ausgewertet werden kann. Öffne anschließend /model erneut.
• Windows meldet, dass Bash nicht gefunden wurde: Installiere Git for Windows oder lege shellPath in ~/.pi/agent/settings.json fest. Rückwärtsschrägstriche müssen in JSON doppelt geschrieben werden.
• Die Anfrage wird abgelehnt: Prüfe, ob api auf openai-completions gesetzt ist und baseUrl mit /v1 endet. Aktiviere keine zusätzlichen Kompatibilitätsoptionen, nur weil der andere Dienst sich als kompatibel bezeichnet.
• Die Modell-ID ist ungültig: Kopiere sie erneut aus der aktuellen Modellliste von OmniProxy.

Offizielle Referenzen

Die Installationsbefehle findest du auf der Pi-Website und im Quickstart. Informationen zur Modelldatei findest du unter Choose a Model und Configuration. Die Windows-Befehlsumgebung wird unter Run Pi on Windows beschrieben. Die in den Beispielen verwendeten Modell-IDs findest du in der Gemini-Modellliste und auf der xAI-Modellseite.

Ersetze jeden Platzhalter durch Werte aus deiner OmniProxy-Konfiguration. Veröffentliche niemals einen echten Schlüssel.

Ein gespeichertes Ergebnis oder HTTP 200 allein beweist keine vollständige Agenten-Kompatibilität. Prüfe Quelle und Modell im OmniProxy-Aufrufprotokoll.

Offizielle Quellen · Pi ↗