Einrichtung einer benutzerdefinierten IronClaw-API: Anbieter, Schlüssel und Datenschutzgrenzen

IronClaw nimmt eine benutzerdefinierte API in einem Block mit vier Feldern entgegen: einen [llm.default]-Slot in ~/.ironclaw/reborn/config.toml mit provider_id, base_url, model und api_key_env — oder, wenn kein Slot vorhanden ist, die Umgebungsvariablen LLM_BACKEND / LLM_BASE_URL / LLM_API_KEY, auf die es zurückgreift. Beide Formen sind aktuell und dokumentiert. Was die Konfigurationsseiten nicht an einer Stelle zusammenfassen, ist die Liste der Funktionen, die ein benutzerdefinierter Endpunkt anschließend nicht erhält — darunter natives Streaming, Modellentdeckung, Anthropic-cache_control-Breakpoints und eine genaue Kostenanzeige — und genau diese Liste sollten Sie lesen, bevor Sie einen Anbieter auswählen.

Zunächst eine Abgrenzung, weil die Suchergebnisse von anderen Produkten dominiert werden. Diese Seite handelt von github.com/nearai/ironclaw, das in den Metadaten seines eigenen Repositorys als „IronClaw is an Agent OS focused on privacy, security and extensibility“ beschrieben wird: Rust, nicht archiviert und kein Fork, 12,626 Sterne, erstellt am 3. Februar 2026 und zuletzt am 21. September 2026 gepusht (GitHub API, am selben Tag). Es handelt sich nicht um die Corsair-Gamingmaus dieses Namens, das Tabletop-RPG von Sanguine Productions, den IRONCLAW-Kryptotoken oder das nicht verwandte Repository JoasASantos/ironclaw — deren Preise und Konfigurationen gehören nicht auf diese Seite. Die maßgebliche Dokumentation befindet sich unter docs.ironclaw.com und im eigenen docs/-Verzeichnis des Repositorys; ein Drittanbieter-Mintlify-Spiegel rankt für dieselben Titel und kann veraltet sein.

Die Zuordnung ist es wert, zitiert statt paraphrasiert zu werden, weil sich die eigenen Präsenzen des Anbieters unterscheiden: ironclaw.com stellt neben einem NEAR-Logo „Built by“ und im Text die Worte „Near Foundation“ dar sowie in der Fußzeile „— by NEAR AI“, während die GitHub-Organisation nearai lautet.

Die minimale Konfiguration eines benutzerdefinierten IronClaw-Anbieters

Die Slot-Struktur in ironclaw_config akzeptiert genau vier optionale Felder, und die zugehörigen Dokumentationskommentare beschreiben sie als Überschreibungen des Katalogeintrags: model überschreibt default_model des Anbieters, api_key_env überschreibt api_key_env und base_url überschreibt default_base_url. Die Anbieterdokumentation ergänzt, dass base_url „auch bei jedem anderen Anbieter funktioniert, wenn Sie ihn über einen Proxy oder einen regionalen Endpunkt leiten müssen“ — dies ist also nicht nur eine Funktion des generischen Adapters.

[llm.default]
provider_id = "openai_compatible"
base_url    = "https://api.kunavo.com/v1"
model       = "claude-sonnet-4-6"
api_key_env = "LLM_API_KEY"

Drei Regeln, die ins Gewicht fallen. Das Weglassen von base_url ist fatal und wird nicht durch einen Standardwert ersetzt: Laut Dokumentation „zeigt der Slot dann nirgendwohin und die Modellauflösung schlägt fehl“, und der Katalogeintrag openai_compatible enthält base_url_required: true. api_key_env erwartet einen Variablennamen, niemals einen Schlüssel — ein eingefügtes Geheimnis wird „beim Parsen abgelehnt und nicht stillschweigend akzeptiert“, während ironclaw config set <provider>.api_key mit verborgener Eingabe danach fragt. Nichts wird wirksam, bevor ein Neustart erfolgt: config set „startet nichts neu“, sondern gibt den noch auszuführenden Schritt ironclaw service restart aus. Und erwarten Sie nicht, dass config set den Slot für Sie schreibt — auf der Konfigurationsseite wird [llm.default] als einer der Abschnitte aufgeführt, die „direkt in config.toml bearbeitet“ werden, und config set „lehnt einen nicht unterstützten Schlüssel ab, statt stillschweigend nichts zu tun“.

Die Umgebungsvariablenform ist der dokumentierte Rückfall, wenn [llm.default] fehlt, und die Dokumentation entscheidet die Wahl eindeutig: „Beide funktionieren … Bevorzugen Sie den TOML-Slot für eine dauerhafte Installation und die Umgebungsvariablenform für einmalige Ausführungen und Container.“

export LLM_BACKEND=openai_compatible
export LLM_BASE_URL=https://api.kunavo.com/v1
export LLM_API_KEY=sk-kn-...
export LLM_MODEL=claude-sonnet-4-6

# optional: LLM_EXTRA_HEADERS is the openai_compatible entry's
# extra_headers_env; the timeout is a general .env.example setting
export LLM_EXTRA_HEADERS=X-Title:MyAgent
export LLM_REQUEST_TIMEOUT_SECS=120

Die Auflösungsreihenfolge lautet compiled defaults < config.toml < environment variables < CLI flags, sodass eine exportierte Variable unbemerkt Vorrang vor der Datei hat, die Sie gerade bearbeitet haben. Der CLI-Weg vermeidet die manuelle Bearbeitung vollständig: ironclaw models list, dann ironclaw models set-provider <id> --model <model>, dann ironclaw models status. Bestätigen Sie Ihre Pfade mit ironclaw config path, statt einer der dokumentierten Angaben zu vertrauen — auf der Quickstart-Seite heißt es, alles befinde sich unter ~/.ironclaw, während die Konfigurations- und Onboarding-Seiten ~/.ironclaw/reborn nennen. Eine betriebliche Falle für gehostete Nutzer: Auf der Konfigurationsseite steht, dass ironclaw service-Befehle „auf einer von NEAR AI gehosteten Instanz nicht funktionieren — es gibt dort keinen Benutzerdienst-Manager, mit dem sie kommunizieren könnten“. Für ironclaw config melden Sie sich daher per SSH an und starten den Dienst anschließend im Agent Dashboard neu. Alle Zitate stammen aus dem main-Branch und wurden am 21. September 2026 gelesen.

Was ein benutzerdefinierter Endpunkt nicht erreicht

Dies sind IronClaws eigene Aussagen über das beabsichtigte Laufzeitverhalten, gelesen aus Quell- und Vertragsdateien im main. Es handelt sich nicht um beobachtete Ausführungen, und main lag beim Lesen vor dem Release-Tag 1.4.0 — laut GitHub-Releases-API veröffentlicht am 28. August 2026.

IronClaws Katalog ist ein Chat-Katalog, und Kunavo bietet kein Embedding-, Text-to-Speech- oder Speech-to-Text-Modell an. Jeder Teil Ihrer Einrichtung, der eines davon benötigt, muss daher vollständig auf einen anderen Ort verweisen.

IronClaws Kostenanzeige ist nicht Ihre Rechnung

Innerhalb von IronClaw berechnen zwei getrennte Pfade Geld, sie widersprechen sich, und keiner liest Ihren Anbieter aus. price_usage() in ironclaw_common bepreist anhand einer fest codierten Tabelle pro Token und fällt auf default_cost() zurück — 0.0000025 für Eingaben und 0.00001 pro Token, also ein GPT-4o-ähnlicher Preis von $2.50 / $10.00 pro Million — mit der angegebenen Begründung, dass „ein neues kostenpflichtiges Modell niemals stillschweigend mit null bepreist wird“. Derweil macht StaticModelCostTable des Loop-Hosts bei Budgetreservierungen das Gegenteil: Ein Profil, das in seiner Tabelle fehlt, „fällt auf None zurück, was der Buchhalter als kostenlos behandelt“. Und auf dem Pfad llm_costs wird der Rabatt für Cache-Lesevorgänge anhand eines Teilstrings im Modellnamen geraten — claude teilt durch zehn, gpt oder ein Präfix o1/o3/o4 durch zwei, alles andere durch eins.

Die praktische Folge ist, dass IronClaws budget.user_daily_usd, budget.pause_at und die übrigen Schlüssel aus [budget] eine Schätzung überwachen, keine Belastung. Bei einem ständig laufenden Agenten lohnt es sich dennoch, sie zu setzen — ein außer Kontrolle geratener Loop, der früh gestoppt wird, ist genau der Zweck —, aber gleichen Sie sie mit der vom Anbieter aufgezeichneten Nutzung ab und nicht mit der Zahl auf dem Bildschirm.

Eine Beispielberechnung für einen Agententag

Dies ist eine Token-Berechnung, keine gemessenen Aufgabenkosten und keine Rechnungsobergrenze. Nehmen wir einen Tag Agentenaktivität mit insgesamt 1.000.000 nicht zwischengespeicherten Eingabetokens und 40.000 Ausgabetokens an — eine Annahme zur Veranschaulichung, gewählt, weil eine ständig laufende Laufzeit Eingaben über Heartbeat-Ticks und Routinen ansammelt statt über lange Antworten. Die Preise sind aktuelle Kunavo-Katalog-Preise pro Million Tokens.

Die letzte Spalte enthält die nützliche Überraschung: Sie ist eine Eigenschaft der ID-Zeichenkette und nicht des Modells. vision_models.rs gleicht eine feste Liste per Teilstring ab, die claude-opus-, claude-sonnet-, claude-haiku- und claude-fable- enthält; diese IDs leiten Bildanhänge weiter. Die übrigen IDs in der obigen Tabelle stimmen mit keinem von gpt-4o, gemini-1.5, gemini-2 oder dem Rest der Liste überein und würden als reiner Text eingestuft. Bei einem Fehlschlag sendet das Loop-Host-Gateway den Nachrichtentext ohne die Bildteile und erzeugt keinen Fehler — das dauerhafte Transkript behält einen <attachments>-Verweis, aber das Modell sieht das Bild nie. Lesen Sie die Musterliste anhand der exakten ID, die Sie eingeben möchten, bevor Sie davon ausgehen, dass Bildeingaben funktionieren. Skalieren Sie die Dollarbeträge anhand Ihrer eigenen Anzahl an Tagen, bevor Sie sie als Budget betrachten. Kunavos Katalogbetrag ist eine Abrechnungsuntergrenze und keine Obergrenze: Wenn der Upstream seine Belastung meldet, entspricht die Rechnung dem höheren Wert aus den Katalogkosten und den Upstream-Kosten multipliziert mit dem jeweils geltenden Aufschlag. Cache-Gebühren und externe Tools sind in diesem Beispiel nicht enthalten, und die minimale Aufladung beträgt $10 als Prepaid-Guthaben — eine Mindestfinanzierung, keine Aufgabengebühr und kein Abonnement. Siehe Abrechnungsdetails.

Welche Route gewinnt, und was IronClaw selbst kostet

Die Software ist kostenlos: Im Repository-Stammverzeichnis befinden sich sowohl LICENSE-APACHE als auch LICENSE-MIT, und die README nennt MIT OR Apache 2.0. Es gibt keine kostenpflichtige Edition der Binärdatei und keine Lizenzgebühr. Sie bezahlen für Tokens sowie gegebenenfalls für das Hosting des Anbieters.

Die Preise der gehosteten Tarife wurden am 21. September 2026 von ironclaw.com abgelesen; es gibt keine Seite /pricing, die Tarife befinden sich auf der Startseite, und das gerenderte Markup zeigt die 5 $ in einem durchgestrichenen Span mit 0 $ als aktuellem Preis. Auf der Startseite steht außerdem „Bis zu 5 Agenten in einer Trusted Execution Environment mit bis zu 130 Mio. Tokens pro Monat starten“ — dieser Satz steht über allen drei Karten und nennt keinen Tarif; ordnen Sie ihn daher keinem einzelnen Tarif zu. Drei Dinge konnte dieser Leitfaden nicht feststellen und wird sie nicht erraten: ob die gehosteten Tarife überhaupt einen Drittanbieter-Schlüssel erlauben, was das enthaltene Guthaben tatsächlich kauft oder was geschieht, wenn es aufgebraucht ist, und zu welchem Tarif die Zahl 130 Mio. gehört. Die Tokenpreise wurden am selben Tag von near.ai/pricing abgelesen; dort steht „Es gibt keine Plattformgebühr zusätzlich zum Modellpreis“, und die Angaben beziehen sich ausschließlich auf die vertraulichen Textmodelle des Dienstes.

Eine Datenschutzgrenze sollte ausdrücklich genannt werden, denn sie ist der Grund, warum sich Menschen für diese Laufzeitumgebung entscheiden. Die Kontrollen, die IronClaws eigene README und Sicherheitsseite beschreiben — Geheimnisse „at rest verschlüsselt“ und an der Host-Grenze injiziert, die WASM-Sandbox für nicht vertrauenswürdige Tools, eine Zulassungsliste für Endpunkte und Leckerkennung — sind lokale Kontrollen über den Rechner, auf dem der Agent läuft. Die Hardware-Beglaubigung ist eine separate Eigenschaft der NEAR AI Cloud: near.ai sagt, dass die Inferenz dort „in einer vertraulichen Intel-TDX- + NVIDIA-GPU-Enklave ausgeführt wird“ und dass „jede Antwort ein überprüfbares Hardware-Zitat enthält“. Wenn Sie IronClaw auf einen Drittanbieter-Endpunkt richten, werden Prompt-Inhalte gemäß den Bedingungen dieses Endpunkts an ihn gesendet; nichts aus einer der beiden Listen folgt dorthin. Die vom Anbieter verfasste Tabelle „OpenClaw vs IronClaw“ auf ironclaw.com ist Marketing einer Seite und kein neutraler Vergleich — und seien Sie bei Suchergebnissen vorsichtig: In einer am 17. September 2026 erstellten Stichprobe einer Ergebnisseite lieferten die vier Suchformen best api for ironclaw, cheapest api for ironclaw, best model for ironclaw und ironclaw custom provider jeweils mindestens acht OpenClaw-Ergebnisse unter den Top Ten, deren Modellrankings ein anderes Produkt beschreiben.

Richten Sie es ein und prüfen Sie dann die erste Abbuchung

Kunavo veröffentlicht einen OpenAI-kompatiblen Endpunkt unter https://api.kunavo.com/v1 sowie einen Anthropic-kompatiblen Endpunkt, die den Provider-IDs openai_compatible und anthropic zugeordnet sind. Kunavo hat IronClaw nicht zur Laufzeit getestet. Betrachten Sie den obigen Block daher als Ausgangspunkt auf Basis dokumentierter Protokolle und nicht als Kompatibilitätszusage: Halten Sie eine funktionierende Route bereit, führen Sie eine begrenzte Aufgabe aus und lesen Sie die Belastung ab, die Ihr Konto tatsächlich verzeichnet hat. Wenn Sie Goose von IronClaw über ACP steuern — .env.example dokumentiert die Agent Client Protocol-Sandbox und den Befehl ironclaw acp add goose — behandelt die Goose-Integration diese Seite separat, und das Erstellen eines Kunavo-Kontos lädt einen Schlüssel auf, sobald Sie bereit sind. Informationen zu den umliegenden Optionen finden Sie in der Referenz zur OpenAI-kompatiblen API, bei OpenRouter-Alternativen und in der KI-Kostenoptimierung.

Häufig gestellte Fragen

Repository-Metadaten, providers.json, CONTRACT.md, llm_costs.rs, vision_models.rs, der docs/-Baum, ironclaw.com und near.ai/pricing wurden am 21. September 2026 aus dem main-Branch und nicht aus dem Release-Tag 1.4.0 abgelesen. Es wurde keine IronClaw-Anfrage an einen Kunavo-Endpunkt gesendet; jede Kompatibilitätsaussage hier ist eine Auswertung der Dokumentation beider Seiten. Die Kunavo-Tokenpreise stammen aus dem Live-Katalog, und jedes Dollarbeispiel ist eine beispielhafte Tokenberechnung.