OpenHands

Settings → LLM → Advanced erwartet drei Felder — Custom Model, Base URL, API Key — wobei die Modell-ID das Präfix openai/ trägt und die Basis-URL /v1 behält.

# Settings → LLM → Advanced  (toggle "Advanced" on first)
Custom Model   openai/claude-sonnet-5
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...

# The "openai/" prefix is the provider, not a vendor: it tells OpenHands to
# speak the OpenAI Chat Completions protocol to the Base URL above. The model
# id after the slash is Kunavo's, and resolves at Kunavo.
#
# Keep the /v1. It belongs to the openai/ prefix — a litellm_proxy/ model
# takes the bare origin instead, which is the opposite convention.

Schritt für Schritt

1. Erstellen Sie unter /app/keys einen Schlüssel und kopieren Sie ihn — er wird nur einmal angezeigt.
2. Öffnen Sie Einstellungen → LLM und aktivieren Sie den Schalter Advanced. Die drei Felder erscheinen in dieser Reihenfolge: Custom Model, Base URL, API Key.
3. Geben Sie die Modell-ID mit Präfix ein — openai/claude-sonnet-5, nicht claude-sonnet-5. Die von Kunavo bereitgestellten IDs erhalten Sie über GET /v1/models. Es handelt sich um dieselbe Liste, aus der laut eigener Dokumentation von OpenHands eine benutzerdefinierte ID stammen soll.
4. Fügen Sie https://api.kunavo.com/v1 in Base URL und Ihren Schlüssel in API Key ein. Klicken Sie anschließend auf Änderungen speichern. Laut OpenHands-Dokumentation überprüft das Speichern eines lokalen Profils zuerst die Konfiguration anhand des Backends und blockiert das Speichern bei einem Fehler. Eine Fehlermeldung an dieser Stelle bedeutet daher eine tatsächliche Zurückweisung und ist kein bloßer Schönheitsfehler.
5. Prüfen Sie, was das Backend erreichen kann, nicht was Ihr Browser erreicht. Die Basis-URL muss von dem Rechner aus aufgelöst werden können, auf dem der Agent Server läuft. Laut Dokumentation ist 127.0.0.1 der Container, wenn Agent Canvas in Docker läuft. Ein öffentlicher Endpunkt wie der von Kunavo ist unkompliziert; ein vorgeschalteter Unternehmensproxy hingegen nicht.
6. Starten Sie eine neue Unterhaltung und geben Sie ihr eine Aufgabe, bei der eine Datei gelesen und bearbeitet wird. OpenHands weist darauf hin, dass ein gespeichertes LLM für neue Unterhaltungen gilt und ältere Unterhaltungen erst neu gestartet werden müssen. Ein Durchlauf, der die Tools verwendet, verrät mehr über die Kombination als eine Begrüßung.

Abgeglichen mit Die Seite „Language Model (LLM) Settings“ von OpenHands am 21. September 2026. Einstellungen von Drittanbietern können sich ändern; wenn ein Feldname hier nicht mehr mit deiner Ansicht übereinstimmt, ist diese Seite maßgeblich, nicht diese hier.

Vor dem Debugging des Clients prüfen

Eine Anfrage klärt, ob der Fehler am Endpunkt, am Schlüssel oder an der Konfigurationsdatei liegt. Wenn diese Anfrage JSON zurückgibt, funktionieren dieselbe Basis-URL und derselbe Schlüssel in OpenHands.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Welche Modell-ID in das Feld gehört

Jedes Textmodell ist über eine Modell-ID erreichbar – die aktuelle Liste findest du unter GET /v1/models, den Katalog mit Preisen auf der Modellseite. Die Tarife sind USD pro 1 Mio. Token, Eingabe / Ausgabe.

Drei Grenzen, die Sie vor der Fehlersuche kennen sollten

OpenHands umfasst mehr Komponenten als eine CLI mit einem einzigen Prozess. Zwei davon sehen wie der LLM-Endpunkt aus, sind es aber nicht. Diese Angaben stammen aus der eigenen Dokumentation von OpenHands, die am oben genannten Datum eingesehen wurde:

1. Die Sandbox ist nicht das Modell. OpenHands führt Ihre Arbeit in einer Agent-Server-Sandbox aus und ruft das Modell über das Netzwerk auf. Das sind separate Komponenten mit separaten Zugangsdaten. Ein hier konfigurierter Schlüssel ermöglicht Modellaufrufe. Er sagt nichts darüber aus, was die Sandbox erreichen kann; ein Netzwerkproblem der Sandbox äußert sich nicht als Authentifizierungsfehler.
2. ACP-Agenten sind vollständig davon getrennt. Agent Canvas kann Aufgaben an Claude Code, Codex oder Gemini CLI als ACP-Agent delegieren. Auf der Seite „Configure a Model“ steht, dass diese „ihren Modellzugriff selbst verwalten“. Ein LLM-Profil leitet diesen Unterprozess also nicht um. Wenn Sie Anfragen über Ihren Schlüssel erwartet haben, aber keine sehen, prüfen Sie, welcher Agent tatsächlich läuft. Unter OpenHands im Vergleich zu Claude Code wird diese Aufteilung einschließlich der Regel zur Priorität von Zugangsdaten erläutert, die darüber entscheidet.
3. Profile und die Obergrenze von 10 Profilen. Eine gespeicherte Konfiguration wird zu einem LLM-Profil. Das zuletzt gespeicherte Profil wird für neue Unterhaltungen aktiv. Zwischen Profilen kann während einer Unterhaltung gewechselt werden, ohne den Kontext zu verlieren. So lassen sich eine günstige und eine teure Modell-ID mit einem einzigen Schlüssel nutzen. Die Dokumentation begrenzt die Zahl auf 10 Profile pro Konto. In einer Provider-Verbindung werden Provider, API-Schlüssel und eine optionale Basis-URL einmalig für mehrere Profile hinterlegt. Auf derselben Seite steht, dass dieser Bereich bei lokalen Agent-Server-Backends verfügbar ist und bei einem OpenHands-Cloud-Backend ausgeblendet wird.