goose installieren und einen benutzerdefinierten Provider konfigurieren

goose ist ein universeller KI-Assistent, der auf deinem Computer läuft. Neben Programmieraufgaben kann er auch Recherchen, Schreibarbeiten, Automatisierungen und Datenaufbereitung übernehmen. Du kannst ihn als Desktop-App, im Terminal oder über eine Schnittstelle verwenden. Desktop- und Terminalversion nutzen dieselbe Modellkonfiguration. Er eignet sich für wiederkehrende Programmierarbeiten und kann außerdem eine Verbindung zu GitHub, Datenbanken und Dateien herstellen.

Vorbereitung vor der Installation

goose bietet zwei Installationsvarianten: Desktop und CLI. Desktop ist die grafische Version mit Fenstern, während die CLI über Befehle im Terminal verwendet wird. Beide nutzen dieselbe Kernkonfiguration, einschließlich Provider und Modelle. Ein Provider ist dabei die Verbindungskonfiguration, die goose mitteilt, welchen Modelldienst es verwenden soll.

Mit Benutzeroberfläche

goose Desktop

• Unter macOS zip herunterladen
• Oder brew cask verwenden
• Unter Linux das Installationspaket verwenden

Nur Terminal

goose CLI

• download_cli.sh
• Oder Homebrew CLI
• Danach goose session

Windows

Zuerst Umgebung auswählen

• Git Bash oder MSYS2
• PowerShell ist ebenfalls möglich
• Wenn der Befehl nicht gefunden wird, zu PATH hinzufügen

Halte vor dem Start die Modell-ID aus der aktuellen Modellliste bereit. Die Modell-ID ist der Name, mit dem der Modelldienst ein bestimmtes Modell identifiziert. Sie muss vollständig übernommen werden.

Installation und erster Start

Grafische Oberfläche verwenden

Für macOS werden zwei Installationswege angeboten:

• Lade die Anwendung von der Installationsseite herunter. Dort gibt es Versionen für macOS Silicon und macOS Intel. Entpacke nach dem Download die ZIP-Datei und starte das darin enthaltene Programm.
• Oder verwende Homebrew:

brew install --cask block-goose

Damit wird dieselbe Anwendung heruntergeladen; außerdem können Aktualisierungen darüber verwaltet werden.

Wenn auf einem Apple Mac M3 nach dem Öffnen kein Fenster erscheint, prüfe, ob ~/.config les- und beschreibbar ist. goose benötigt dieses Verzeichnis zum Schreiben von Protokollen.

Lade die Linux-Desktopversion von der Installationsseite herunter. Aufgeführt sind DEB für Ubuntu/Debian, RPM für RHEL/Fedora und Flatpak. Unter Debian oder Ubuntu gehst du wie folgt vor: Lade die DEB-Datei herunter, wechsle in das Verzeichnis, in dem sie gespeichert ist, und führe sudo dpkg -i (filename).deb aus. Öffne goose anschließend über das Anwendungsmenü. Ersetze (filename) durch den tatsächlichen Dateinamen.

Lade die Windows-Desktopversion von der Installationsseite herunter, entpacke die ZIP-Datei und starte das darin enthaltene Programm.

Nur das Terminal verwenden

Führe unter macOS und Linux Folgendes aus:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

Wenn du während der Installation keine interaktive Konfiguration durchführen möchtest, stelle CONFIGURE=false voran:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

Unter macOS kannst du außerdem Folgendes ausführen:

brew install block-goose-cli

Eine bereits installierte CLI aktualisierst du mit:

goose update

Unter Windows ist eine der folgenden drei Umgebungen erforderlich: Git Bash, das mit Git for Windows ausgeliefert und als empfohlene Option gekennzeichnet wird, MSYS2 oder das in Windows 10/11 enthaltene PowerShell. Verwende in Git Bash und MSYS2 denselben oben gezeigten Befehl mit download_cli.sh. Lade in PowerShell zunächst das Skript herunter und führe es anschließend aus:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"
.\download_cli.ps1

Wenn gemeldet wird, dass sich goose nicht im PATH befindet, füge entsprechend der Installationsseite ~/.local/bin oder %USERPROFILE%\.local\bin zur Konfiguration der aktuellen Shell hinzu und öffne das Terminal danach erneut. PATH ist eine Gruppe von Verzeichnissen, in denen das Terminal nach Programmen sucht. Fehlt das Installationsverzeichnis dort, lässt sich ein bereits installiertes Programm möglicherweise nicht direkt über seinen Namen starten.

Am 2026-10-09 war die CLI-Version 1.54.0. Das Installationsskript legt das Programm standardmäßig unter ~/.local/bin ab. Mit der Umgebungsvariable GOOSE_BIN_DIR kannst du dieses Verzeichnis ändern. Nach einer solchen Änderung trägt das Skript den Pfad nicht automatisch in die Shell-Konfiguration ein, und das Terminal weist darauf hin, dass sich das Verzeichnis nicht im PATH befindet. Füge das Verzeichnis zum PATH hinzu oder starte das Programm über seinen vollständigen Pfad.

Bei der ersten Verwendung fordert goose dich zur Konfiguration eines Providers auf. Du kannst die integrierten Anbieter zunächst überspringen und wie im nächsten Abschnitt einen benutzerdefinierten Provider hinzufügen. Wechsle im Terminal in das gewünschte Arbeitsverzeichnis und führe Folgendes aus:

goose session

Verbindungsparameter aus OmniProxy abrufen

Bereite die Adresse, den Schlüssel und den Modellnamen aus deiner eigenen OmniProxy-Instanz vor. Im Beispiel für einen benutzerdefinierten Provider endet base_url mit /v1/chat/completions. Verwende deshalb auch hier dieses Format:

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   Aus der aktuellen OmniProxy-Modellliste kopieren; mehrere Einträge durch englische Kommas trennen

Kopiere den Modellnamen vollständig aus der aktuellen OmniProxy-Liste und behalte dabei auch Schrägstriche bei. Zwei Vergleichs-IDs in der Anbieterdokumentation vom 2026-10-09 waren grok-4.7 für Grok und gpt-6-luna aus der OpenAI-Dokumentation. gpt-6-luna unterstützt Chat Completions. Funktionsaufrufe werden in Chat Completions nur unterstützt, wenn reasoning_effort auf none gesetzt ist. Übernimm keine Namen, die nicht in der Liste enthalten sind.

Werkzeugkonfiguration eintragen

Benutzerdefinierte Provider verwenden ein mit OpenAI, Anthropic oder Ollama kompatibles Format. Ein kompatibles Format bedeutet hier, dass das Werkzeug seine Anfragen über eine entsprechende allgemeine Schnittstelle sendet. Wähle für die Verbindung mit OmniProxy OpenAI Compatible.

Desktopversion

1. Klicke oben links auf die Schaltfläche, um die Seitenleiste zu öffnen.
2. Klicke auf Settings.
3. Klicke auf Models.
4. Klicke auf Configure providers.
5. Klicke unten im Fenster auf Add Custom Provider.
6. Wähle unter Provider Type die Option OpenAI Compatible. Als Display Name kannst du OmniProxy eintragen. Trage unter API URL die Adresse aus dem vorherigen Abschnitt ein. Wenn ein Schlüssel erforderlich ist, aktiviere die Option für einen API Key und trage den OmniProxy-Schlüssel ein. Gib unter Available Models die Modellnamen ein und trenne mehrere Modelle durch englische Kommas.
7. Klicke auf Create Provider.

In der Desktopversion lassen sich in diesem Fenster derzeit keine benutzerdefinierten Anfrage-Header definieren. Wenn du solche Header benötigst, bearbeite nach dem Erstellen die Konfigurationsdatei.

Terminal

Führe Folgendes aus:

goose configure

Wähle Custom Providers und anschließend Add A Custom Provider. Wähle als API Type die Option OpenAI Compatible und gib dann entsprechend den Eingabeaufforderungen den Namen, die API URL, die Information, ob ein Schlüssel erforderlich ist, die Modellnamen und die Unterstützung für Streaming-Antworten an.

Wenn bei der manuellen Konfiguration unter Windows ein Fehler mit dem Schlüsselbund auftritt, wähle bei der Frage, ob der Schlüssel im keyring gespeichert werden soll, die Option zum Nicht-Speichern und verwende stattdessen eine Umgebungsvariable. Führe danach goose configure erneut aus. Der Schlüsselbund ist ein kleiner sicherer Systemspeicher für Schlüssel.

Konfigurationsdatei

Die angegebenen Verzeichnisse sind:

• macOS und Linux: ~/.config/goose/custom_providers/
• Windows: %APPDATA%\Block\goose\config\custom_providers\

Du kannst die Datei nach dem folgenden Beispiel aufbauen. Ersetze Name, Adresse und Modelle durch deine eigenen Werte. Speichere den Schlüssel in der unter api_key_env angegebenen Umgebungsvariable und schreibe den echten Schlüssel nicht in die Datei:

{
  "name": "omniproxy",
  "engine": "openai",
  "display_name": "OmniProxy",
  "api_key_env": "OMNIPROXY_API_KEY",
  "base_url": "https://your-omniproxy-origin.example/v1/chat/completions",
  "models": [
    { "name": "grok-4.7", "context_limit": 128000 },
    { "name": "gpt-6-luna", "context_limit": 128000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Behalte für context_limit wie im Beispiel eine Zahl bei. Der tatsächliche Kontext hängt vom Modell und von OmniProxy ab. Betrachte den Beispielwert nicht als offizielle Obergrenze des jeweiligen Modells. Führe vor der Verwendung Folgendes aus:

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

Wechsle anschließend in das Arbeitsverzeichnis und führe Folgendes aus:

goose session --provider omniproxy --model grok-4.7

Ersetze den Wert für --model durch die vollständige ID aus der Liste. goose session besitzt keinen Unterbefehl namens start. Anstelle von --provider und --model kannst du auch die Umgebungsvariablen GOOSE_PROVIDER und GOOSE_MODEL verwenden. Selbst wenn das Gateway den Schlüssel nicht überprüft, muss OMNIPROXY_API_KEY einen Wert enthalten. Dafür kann eine beliebige Platzhalterzeichenfolge verwendet werden, die nur lokal zum Einsatz kommt. Am 2026-10-09 konnte damit eine Datei gelesen werden.

Benutzeroberfläche

Settings

• Settings in der Seitenleiste
• Seite Models
• Add Custom Provider

Terminal

goose configure

• Custom Providers auswählen
• Dann Hinzufügen auswählen
• Als Typ OpenAI Compatible wählen

Datei

custom_providers

• Unter macOS und Linux in ~/.config
• Unter Windows in APPDATA
• base_url gemäß offiziellem Beispiel

Eine reale Aufgabe überprüfen

Wechsle in ein Verzeichnis mit einer normalen Datei und starte den im vorherigen Abschnitt gezeigten Befehl goose session. Weise goose an, die erste Zeile einer bestimmten Datei auszugeben. Als Ergebnis muss der Dateiinhalt erscheinen und nicht nur eine Meldung, dass die Konfiguration gespeichert wurde.

Zum Lesen von Dateien oder Ausführen von Befehlen benötigt die Sitzung die Developer-Erweiterung. Diese Erweiterung ist ein Werkzeugmodul, mit dem goose lokale Dateien und Befehle verarbeiten kann. In der Standardkonfiguration ist sie normalerweise bereits enthalten. Wenn goose antwortet, dass keine Werkzeuge für Dateien verfügbar sind, ergänze den Befehl um:

--with-builtin developer

Füge nicht gleichzeitig --no-profile hinzu, da dieser Parameter die Standarderweiterungen deaktiviert.

Am 2026-10-09 konnte goose 1.54.0 die erste Zeile der angegebenen Datei lesen. Die erste Antwort kann ungefähr eine Minute dauern.

Prüfe anschließend in den Aufrufprotokollen von OmniProxy die Quelle und den Modellnamen.

Start

Sitzung lässt sich öffnen

• goose session
• Provider ist der soeben hinzugefügte
• Modellname steht in der Liste

Aufgabe

Aufgabe wurde tatsächlich ausgeführt

• Zum Beispiel das aktuelle Verzeichnis auflisten
• Antwort prüfen
• Nicht nur auf die erfolgreiche Speicherung achten

Protokoll

Im Gateway sichtbar

• Adresse muss dem Dokumentationsbeispiel entsprechen
• Schlüssel nicht im Repository speichern
• Modell-ID stimmt mit der Liste überein

Häufige Fehler

• Der Befehl goose wird nicht gefunden: Füge entsprechend der Installationsseite das Installationsverzeichnis zum PATH hinzu und öffne das Terminal erneut.
• Auf einem M3 erscheint kein Fenster der Desktopversion: Prüfe die Lese- und Schreibberechtigungen für ~/.config.
• Der Schlüsselbund schlägt fehl: Speichere den Schlüssel nicht im keyring, sondern verwende eine Umgebungsvariable.
• Das Modell befindet sich nicht in der Liste: In der Desktopversion kannst du über Use custom model einen Modellnamen manuell eintragen. In goose configure lässt sich kein benutzerdefinierter Modellname eingeben. Verwende im Terminal stattdessen die Desktopversion oder ändere GOOSE_MODEL direkt in der Konfiguration.
• Die Adresse ist nicht erreichbar: Prüfe, ob die API URL wie im Beispiel mit /v1/chat/completions endet und ob OmniProxy ausgeführt wird.
• goose meldet, dass die Datei nicht gelesen werden kann: Füge die Developer-Erweiterung hinzu und verwende nicht --no-profile.
• Die Antwort lautet unsupported Responses role: system: Die Adresse ist normalerweise korrekt. Verwende eine andere vollständige ID aus der Modellliste.

Offizielle Referenzen

Informationen zur Installation findest du unter Install goose. Informationen zu benutzerdefinierten Providern findest du unter goose providers. Die als Beispiele verwendeten Modell-IDs findest du auf der xAI-Modellseite und unter GPT-6 Luna.

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 · goose ↗