OpenHands + JoinGonka Gateway: Agent auf eigenem Endpunkt

Das Projekt hat heute mehrere Schnittstellen, und je nachdem, welche bei Ihnen läuft, unterscheidet sich der Ort der Modelleinstellungen. Die Werte selbst sind überall gleich, nur der Pfad dorthin variiert.

Für Agent Canvas sind Node.js und uv erforderlich – der lokale Server des Agenten läuft darauf (Details in der Installationsanleitung). Die Anleitung nennt Node.js 22.12 oder neuer, aber das Paket selbst deklariert ab Version 1.17 Node.js 24 oder neuer – verwenden Sie 24, um keine Warnung wegen einer inkompatiblen Version zu erhalten. Es gibt auch eine Container-Option: Das Image ghcr.io/openhands/agent-canvas stellt die Schnittstelle unter http://localhost:8000/canvas bereit und sieht nur die Verzeichnisse, die Sie gemountet haben.

JoinGonka Schlüssel. Registrieren Sie sich unter gate.joingonka.ai/register, bestätigen Sie Ihre Adresse und erstellen Sie einen Schlüssel mit dem Präfix jg- im Bereich „API-Keys“. Ein Schlüssel und ein Guthaben gelten für alle Modelle im Netzwerk. In der Liste der Werkzeuge des @joingonka/setup-Installers ist OpenHands nicht enthalten, und das ist kein Versäumnis: Dessen Einstellungen leben in der Oberfläche und im geschützten Backend-Speicher, nicht in einer Text-Konfigurationsdatei, die man von außen sauber bearbeiten könnte.

Schritt 1. Starten Sie Agent Canvas und öffnen Sie Settings > LLM. Der Einrichtungsassistent schlägt einen eigenen OpenHands-Anbieter vor — diesen Schritt können Sie überspringen, da die Einstellungen später leicht wieder aufgerufen werden können.

Schritt 2. Klicken Sie auf Add LLM Profile und wechseln Sie zum Tab Advanced: Der Tab Basic bietet nur Anbieter und Modelle aus der integrierten Liste an.

Schritt 3. Füllen Sie die drei Felder aus:

Schritt 4. Speichern Sie das Profil. Vor dem Speichern überprüft Canvas die Konfiguration mit einer Anfrage vom Backend: Wenn der Schlüssel abgelehnt wird oder das Modell nicht verfügbar ist, wird das Profil nicht gespeichert und Sie sehen eine Fehlermeldung.

Schritt 5. Beginnen Sie eine neue Unterhaltung und senden Sie eine kurze Nachricht. Bereits geöffnete Unterhaltungen laufen weiterhin mit dem Modell, mit dem sie begonnen wurden.

Warum openai/. LiteLLM bestimmt den Anbieter anhand des Modellpräfixes. Das Präfix openai/ bedeutet nicht „Modell von OpenAI“, sondern „mit dem Server über das OpenAI Chat Completions-Protokoll kommunizieren“. Nur das erste Segment wird abgeschnitten, sodass die eigentliche Kennung — deepseek-ai/DeepSeek-V4-Flash-0731 — am Gateway ankommt. In der OpenHands-Dokumentation wird dasselbe Schema am Beispiel von openai/qwen/qwen3.6-35b-a3b gezeigt. Ohne das Präfix verweigert LiteLLM den Dienst mit der Meldung LLM Provider NOT provided.

Warum /v1 und nichts weiter. LiteLLM kontaktiert den Server über den offiziellen OpenAI-Client, der selbst /chat/completions anhängt. Daher muss die Adresse auf /v1 enden: Ohne das Suffix geht die Anfrage an der API vorbei, mit einem zusätzlichen Ende landet sie auf einem Pfad, der nicht existiert. Eine weitere Anforderung von Canvas: Die Adresse muss vom Backend aus erreichbar sein, nicht nur vom Browser aus. Das Gateway ist eine öffentliche HTTPS-Adresse; aus dem Docker-Container ist es genauso sichtbar wie vom Host aus; Tricks wie host.docker.internal werden nur für Modelle auf Ihrem eigenen Rechner benötigt.

Profile für alle drei Modelle. Erstellen Sie ein Profil für jedes Netzwerkmodell und benennen Sie diese kurz — zum Beispiel deepseek, glm und minimax (die Dokumentation erwähnt ein Limit von zehn Profilen). Sie können direkt in der Unterhaltung umschalten, ohne den Kontext zu verlieren: über den Profilauswahl-Button im Eingabefeld oder den Befehl /model glm; /model ohne Argument zeigt die Liste an. Um den Schlüssel nicht in jedes Profil einfügen zu müssen, können Sie ihn einmalig im Block „Provider Connections“ speichern — er ist auf dem lokalen Backend verfügbar.

Früheres Interface in Docker. Die Felder sind dieselben: Settings → Tab LLM → Advanced aktivieren → Custom Model, Base URL, API Key → Save Changes.

Die CLI wird mit einem Befehl über uv installiert und führt beim ersten Start selbst durch die Modellkonfiguration; später kehrt man mit Ctrl+P → Settings dorthin zurück:

uv tool install openhands --python 3.12
openhands

Für Skripte sind Umgebungsvariablen praktischer. Ein wichtiges Detail: Standardmäßig ignoriert die CLI sie und wendet sie nur mit dem Flag --override-with-envs an — für einen einzelnen Lauf, ohne etwas zu speichern:

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

Dasselbe Set funktioniert ohne Oberfläche — für CI und Batch-Aufgaben:

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

Im Headless-Modus arbeitet der Agent immer mit Auto-Genehmigung, also starten Sie ihn dort, wo er alles darf: in einem separaten Verzeichnis oder Container. Das Flag --json verwandelt die Ausgabe in einen Strom von JSONL-Ereignissen — praktisch, um sie in einer Pipeline zu verarbeiten. Genau so haben wir die Verbindung am 21. September 2026 mit CLI 1.16.0 geprüft: Im Kopf der CLI wird Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731 ausgegeben, danach liest der Agent die Datei und antwortet sachlich.

Die gespeicherten CLI-Einstellungen liegen in ~/.openhands/agent_settings.json: Das Modell darin wird durch Bearbeiten von drei Feldern des Blocks llm geändert — model, api_key und base_url. Die Datei von Grund auf neu zu erstellen ist keine gute Idee: Der Assistent beim ersten Start schreibt dort auch die übrigen Agent-Einstellungen hinein, darunter die Verlaufskomprimierung, ohne die ein langes Gespräch ans Kontextfenster stößt.

Wenn Sie den Agenten in eigenen Code einbetten, nimmt das OpenHands SDK dieselben drei Werte entgegen:

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

Der Preis bei Netzmodellen ist einheitlich, daher geht es bei der Auswahl um das Verhalten. Für einen autonomen Agenten sind zwei Zahlen wichtig. Kontextfenster: Jeder Schritt sendet den Verlauf erneut, und je länger das Fenster, desto länger arbeitet der Agent ohne Verluste. Antwortobergrenze: Der Schritt, in dem der Agent eine große Datei vollständig schreibt, muss in eine einzige Antwort passen. In der Tabelle finden Sie die Ergebnisse unseres Durchlaufs derselben Aufgabe (Datei lesen und Fehler finden) über OpenHands CLI 1.16.0 mit SDK 1.21.0.

Ein bewährtes Schema für langwierige Aufgaben folgt dem Rat aus der OpenHands-Dokumentation: mit einem Modell planen, mit einem anderen ausführen. Beginnen Sie das Gespräch mit dem glm-Profil und bitten Sie um einen Plan ohne Dateibearbeitungen; senden Sie dann /model deepseek und geben Sie den Befehl zur Ausführung. Verlauf, Dateien und Aufgabenstatus bleiben beim Umschalten erhalten. Halten Sie das minimax-Profil als drittes bereit: Es ist praktisch, darauf auszuweichen, wenn die anderen beiden zu Stoßzeiten keine Kapazität mehr haben, und in Settings > Application kann man ihm auch die Generierung von Konversationstiteln überlassen.

Verlaufskomprimierung. Selbst ein Fenster von Hunderttausenden von Token ist bei einer stundenlangen Aufgabe begrenzt. In OpenHands ist dafür der Condenser zuständig: Er fasst alte Ereignisse in einer kurzen Zusammenfassung zusammen, was laut Dokumentation die Latenz und den Token-Verbrauch in langen Gesprächen reduziert. Im Agent Canvas lässt er sich unter Settings > Condenser konfigurieren; bei unserem CLI-Durchlauf hat er sich mit einem Schwellenwert von 80 Ereignissen automatisch eingeschaltet.

Modelllimits. OpenHands übernimmt das Kontextfenster und die Antwortobergrenze aus dem LiteLLM-Verzeichnis, aber Gonka-Netzwerkkennungen sind dort nicht enthalten (wir haben LiteLLM 1.81 überprüft), sodass der Agent keine eigenen Werte für diese Modelle hat. Das behindert die Arbeit nicht: Das Gateway wendet die Antwortobergrenze selbst an, gemäß der obigen Tabelle. Wenn Sie Limits explizit festlegen möchten – im SDK sind das die Felder max_input_tokens und max_output_tokens, und im Canvas öffnet der Tab All die vollständige Liste der Profilfelder. Details zum Standardmodell finden Sie im Überblick über DeepSeek V4 Flash.

Sie können von zwei Seiten aus überprüfen, ob Anfragen tatsächlich über das Gateway laufen. Von der Seite von OpenHands aus — ein neues Gespräch und eine kurze Aufgabe wie „Lies die README und fasse sie in einem Satz zusammen“: Der Agent sollte das Tool aufrufen und antworten. Von der Seite des Gateways aus — im Dashboard, Bereich „Nutzung“: Die Anfrage erscheint in der Aufschlüsselung „Nach Modellen“, und im Block „Nach Schlüsseln“ wird die Zeit der letzten Anfrage aktualisiert. Wenn es leer ist, bedeutet dies, dass das Gespräch über ein anderes Profil geführt wird: Überprüfen Sie, welches davon als aktiv markiert ist.

Laut der Dokumentation von OpenHands können die Anzahl der Wiederholungen und die Pausen dazwischen bei 429 über die Variablen LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT und LLM_RETRY_MAX_WAIT konfiguriert werden. Die Standardwerte in der Dokumentation und im SDK weichen voneinander ab, orientieren Sie sich daher an den tatsächlichen Werten: Im Gesprächszustand der CLI 1.16.0 sahen wir 5 Versuche mit Pausen von 8 bis 64 Sekunden.

Über das JoinGonka Gateway kosten Token $0.0069 pro Million bei der Eingabe und $0.021 pro Million bei der Ausgabe — der Preis ist für alle Modelle im Netzwerk gleich und wird auf dieser Seite aus einer Live-Quelle übernommen.

Die Einschätzungen in der rechten Spalte basieren auf den Preisen vom September 2026; wie die Ökonomie von Agenten funktioniert, wird detailliert im Artikel über die günstigste API für AI-Agenten erläutert.

Verbrauchsobergrenze. OpenHands empfiehlt, Ausgabenlimits festzulegen — das Gateway hat dies direkt in das Zahlungsmodell integriert: Das Guthaben ist vorausbezahlt, und der Agent wird nicht mehr ausgeben, als auf dem Konto vorhanden ist. Restguthaben und täglicher Verbrauch sind im Dashboard sichtbar. Erstellen Sie für CI und Hintergrundautomatisierungen einen separaten Schlüssel, damit sich deren Verbrauch nicht mit Ihrem vermischt; untergeordnete Schlüssel mit Tageslimit werden im Artikel über Management Keys beschrieben.

Vertrauensgrenze. Agent Canvas, das über npm gestartet wird, arbeitet mit den Rechten Ihres Benutzers und sieht das gesamte Dateisystem. Für fremden Code verwenden Sie die Variante in Docker: Der Agent sieht nur das eingebundene Verzeichnis. Dies ist eine Eigenschaft von OpenHands selbst und hängt nicht vom Modell-Provider ab.

Der Schriftverkehr bleibt bei Ihnen. Der Gesprächsverlauf wird von OpenHands lokal unter ~/.openhands gespeichert und bei jedem Schritt an das Modell gesendet; das Gateway speichert den Schriftverkehr nicht — Ihre Prompts und Ihr Code bleiben nach der Antwort nicht darauf zurück.

Wenn die Aufgabe Bilder enthält — Screenshots der Benutzeroberfläche, Schemata — erstellen Sie dafür ein separates Profil mit einem Vision-Modell: Die Gonka-Netzwerkmodelle sind textbasiert. Für Code, Befehle und Dateien ist dies keine Einschränkung.