OpenClaw

Ein Eintrag unter models.providers in ~/.openclaw/openclaw.json — baseUrl https://api.kunavo.com, api "anthropic-messages" — verbindet einen ständig aktiven OpenClaw-Agenten mit Claude. cacheRetention wird daneben gesetzt, denn ein benutzerdefinierter Anthropic-Endpunkt erhält erst dann Cache-Markierungen.

// ~/.openclaw/openclaw.json — merge into the file you already have
{
  models: {
    mode: "merge",
    providers: {
      kunavo: {
        baseUrl: "https://api.kunavo.com",   // origin — no /v1 on this wire
        apiKey: "${KUNAVO_API_KEY}",         // from the environment or ~/.openclaw/.env
        api: "anthropic-messages",
        models: [
          {
            id: "claude-sonnet-5",
            name: "Claude Sonnet 5",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1000000,
            contextTokens: 200000,           // optional: compact here, not at 1M
            maxTokens: 32000,
          },
          {
            id: "claude-haiku-4-5",
            name: "Claude Haiku 4.5",
            input: ["text", "image"],
            contextWindow: 200000,
            maxTokens: 16000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "kunavo/claude-sonnet-5" },
      models: {
        // Required for caching: a custom Anthropic endpoint gets no cache
        // markers from OpenClaw until cacheRetention is set explicitly.
        "kunavo/claude-sonnet-5": { params: { cacheRetention: "short" } },
        "kunavo/claude-haiku-4-5": { params: { cacheRetention: "short" } },
      },
    },
  },
}

Schritt für Schritt

1. Erstellen Sie unter /app/keys einen Schlüssel und kopieren Sie ihn — er wird nur einmal angezeigt.
2. Geben Sie dem Gateway den Schlüssel: Fügen Sie KUNAVO_API_KEY=sk-kn-... zu ~/.openclaw/.env hinzu oder exportieren Sie ihn in der Umgebung, in der das Gateway gestartet wird. Beim Laden der Konfiguration wird ${KUNAVO_API_KEY} im Block durch den dort hinterlegten Wert ersetzt.
3. Integrieren Sie den Block in ~/.openclaw/openclaw.json und behalten Sie Ihre vorhandenen Anbieter, Agenten und Kanäle bei. Die Datei verwendet JSON5, daher können die Kommentare bleiben.
4. Führen Sie openclaw config validate aus. OpenClaw verweigert den Start, wenn die Datei eine nicht erkannte Einstellung enthält. Daher ist es besser, einen Tippfehler hier zu finden als erst beim nächsten Neustart.
5. Führen Sie openclaw models list --provider kunavo aus und prüfen Sie, ob beide IDs aufgeführt sind. Wenn ein laufendes Gateway die Änderung noch nicht übernommen hat, führen Sie openclaw gateway restart aus.
6. Starten Sie mit /new eine neue Sitzung — eine bestehende behält das bereits verwendete Modell bei —, senden Sie zwei Nachrichten und lesen Sie dann /usage tokens aus: Für den zweiten Durchgang sollte cacheRead gemeldet werden.

Abgeglichen mit Referenz zu benutzerdefinierten OpenClaw-Anbietern am 5. Oktober 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 OpenClaw.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

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.

Das OpenAI-kompatible Protokoll

Mit demselben Schlüssel sind auch alle anderen Modellfamilien über /v1/chat/completions erreichbar. Registrieren Sie dafür einen zweiten Anbietereintrag, damit die beiden Protokolle getrennt bleiben, und verweisen Sie auf die Modelle mit kunavo-openai/<id>:

// ~/.openclaw/openclaw.json — a second entry, beside "kunavo"
{
  models: {
    providers: {
      "kunavo-openai": {
        baseUrl: "https://api.kunavo.com/v1",   // this wire keeps /v1
        apiKey: "${KUNAVO_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gpt-6-sol",
            name: "GPT-6 Sol",
            reasoning: true,
            input: ["text"],
            contextWindow: 1050000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

// then: /model kunavo-openai/gpt-6-sol

Drei Dinge unterscheiden sich vom Block am Anfang. Die Basis-URL behält /v1 bei, wie in OpenClaws eigenen Beispielen für benutzerdefinierte Anbieter. api lautet openai-completions — das nimmt OpenClaw auch an, wenn ein benutzerdefinierter Anbieter baseUrl, aber kein api angibt. Und maxTokens ist in der Praxis nicht mehr optional: Ist das Ausgabelimit eines Modells unbekannt, sendet OpenClaw über dieses Protokoll überhaupt keine Begrenzung. Kunavo beendet eine Claude-Antwort dann nach 4.096 Token.

Auch Claude-IDs funktionieren hier. Verwenden Sie dieses Protokoll, wenn Sie einen Eintrag für alles möchten. Für Claude ändern sich zwei Dinge: Bei Chat Completions werden die Denkstufen nicht weitergegeben, und Kunavo statt OpenClaw setzt die Zwischenspeicherpunkte.

Prompt-Caching auf den verschiedenen Protokollen

Beim Anthropic-Protokoll setzt OpenClaw die Zwischenspeicherpunkte selbst, bei einem benutzerdefinierten Endpunkt jedoch nur, wenn cacheRetention gesetzt ist. Die Referenz zum Prompt-Caching sagt es ausdrücklich: Der Standardwert short ist nur für die Anbieter anthropic und anthropic-vertex voreingestellt; für alle anderen Routen der Anthropic-Familie ist ein expliziter Wert erforderlich. Kunavos /v1/messages leitet den Anfrageinhalt unverändert weiter und fügt keine Zwischenspeicherpunkte hinzu. Eine Konfiguration ohne diese Zeilen aktiviert daher kein Caching.

short fordert einen Eintrag mit fünf Minuten Laufzeit an, long einen mit einer Stunde. Kunavo leitet beide Markierungen weiter und berechnet für den Schreibzugriff denselben Preis. Prüfen Sie anhand Ihrer eigenen Nutzung, ob ein Eintrag mit einer Stunde Laufzeit beim nächsten Heartbeat noch vorhanden ist, bevor Sie Ihre Taktung darauf abstimmen: Bei einem Durchlauf, der cacheRead meldet, blieb der Cache erhalten; bei einem, der erneut cacheWrite meldet, nicht. /usage tokens und /status zeigen beide Zähler.

Beim OpenAI-kompatiblen Protokoll funktioniert es umgekehrt. OpenClaw sendet keine Cache-Hinweise an einen Proxy-Endpunkt, und Kunavo setzt die Zwischenspeicherpunkte für Claude-Modelle selbst — am System-Prompt, den Werkzeugdefinitionen und am Ende des Gesprächs — sobald der Prompt lang genug ist, um zwischengespeichert zu werden. Es ist keine Konfiguration erforderlich, und GPT-Modelle werden vom jeweiligen Anbieter implizit zwischengespeichert.

Unabhängig davon, welche Seite die Breakpoints setzt, bleibt die Abrechnung gleich. Bei Claude Sonnet 5 kostet ein Cache-Lesezugriff $0.14 pro 1M Token, verglichen mit $1.40 für neue Eingaben. Ein Cache-Schreibzugriff kostet $1.75 — den Aufpreis, den Claude für das Schreiben gegenüber Eingaben berechnet; bei einem Eintrag mit einer Laufzeit von einer Stunde gilt derselbe Satz. Ein Eintrag bleibt fünf Minuten gültig, und jeder Lesezugriff verlängert seine Laufzeit. Was ein Agent bezahlt, hängt daher weniger vom Modell ab als davon, ob seine nächste Anfrage innerhalb dieses Zeitfensters eintrifft. Die Cache-Preise aller Modelle finden Sie auf der Seite zum Prompt-Caching.

OpenClaw kann dieselbe Rechnung lokal anzeigen. Die Zusammenfassung unter /usage cost und die Kostenzeile in /status benötigen für jede Modellzeile ein cost-Objekt. Fehlt es, zeigen sie null an, während Kunavo wie gewohnt abrechnet. Diese Zeilen werden aus dem aktuellen Katalog generiert:

// merge into the rows of models.providers.kunavo.models — USD per 1M tokens
{ id: "claude-sonnet-5", cost: { input: 1.4, output: 7, cacheRead: 0.14, cacheWrite: 1.75 } },
{ id: "claude-haiku-4-5", cost: { input: 0.7, output: 3.5, cacheRead: 0.07, cacheWrite: 0.875 } },
{ id: "claude-opus-5-5", cost: { input: 2.8, output: 14, cacheRead: 0.14, cacheWrite: 3.5 } },
{ id: "claude-fable-5", cost: { input: 7, output: 35, cacheRead: 0.7, cacheWrite: 8.75 } },

Was ein ständig aktiver Agent pro Tag kostet

Ein OpenClaw-Agent verursacht Kosten, auch wenn niemand mit ihm spricht, und zwar durch den Heartbeat: einen geplanten Agentenlauf, der standardmäßig alle 30 Minuten ausgeführt wird, also 48 pro Tag. Wenn nichts anderes festgelegt ist, läuft er in der Hauptsitzung und sendet den Gesprächsverlauf erneut – laut OpenClaw-Referenz umfasst ein solcher Lauf etwa 100.000 Tokens, bei Isolation einige Tausend. Dreißig Minuten sind länger als das fünfminütige Cache-Zeitfenster, daher wird der gesamte Prompt bei jedem Lauf erneut abgerechnet: zum Eingabepreis oder, wenn ein Breakpoint gesetzt ist, zum höheren Schreibpreis. Die Tabelle berechnet die Kosten eines inaktiven Tages zum Eingabepreis, mit 5.000 Tokens für den isolierten Lauf:

Der folgende Block zeigt eine günstige Variante aus dieser Tabelle: Heartbeats mit Haiku in einer isolierten Sitzung, ohne die Bootstrap-Dateien des Workspace und nur während der Wachstunden. Alle darin enthaltenen Einstellungen stammen aus der Heartbeat-Referenz von OpenClaw. Ein längeres Intervall für every ist die andere Stellschraube, und "0m" schaltet den wiederkehrenden Lauf aus.

// ~/.openclaw/openclaw.json — what decides the cost of an idle day
{
  agents: {
    defaults: {
      utilityModel: "kunavo/claude-haiku-4-5",   // titles and other short internal tasks
      heartbeat: {
        every: "30m",                            // the default with an API key
        model: "kunavo/claude-haiku-4-5",        // wake-ups on the cheapest tier
        isolatedSession: true,                   // a fresh session, not the whole conversation
        lightContext: true,                      // skip the workspace bootstrap files
        activeHours: { start: "08:00", end: "24:00" },
      },
    },
  },
}

Die Stunden, in denen der Agent tatsächlich arbeitet, machen die andere Hälfte der Rechnung aus – und hier entscheidet der Cache. Nehmen wir 100 aufeinanderfolgende Anfragen, die jeweils einen Kontext mit 100.000 Tokens erneut senden, zusätzlich 2.000 neue Tokens enthalten und 800 Ausgabe-Tokens zurückgeben. Bei Claude Sonnet 5 sind das etwa $2.31, wenn der Kontext aus dem Cache gelesen wird, und etwa $14.84, wenn bei jeder Anfrage der Kontext als neue Eingabe abgerechnet wird. Gleiche Arbeit, dasselbe Modell: Der Unterschied besteht darin, ob die Breakpoints vorhanden sind und die Anfragen weniger als fünf Minuten auseinanderliegen.

Zur Einordnung, gemessen und nicht angenommen: Über die Kunavo-Konten hinweg, auf denen ein Agent dauerhaft läuft, hat ein aktiver Tag im Median $12.67 gekostet und ein Tag am 90. Perzentil etwa $163. Das sind Beträge, die bis 5. Oktober 2026 abgerechnet wurden, zu den jeweils an den betreffenden Tagen geltenden Tarifen. Es handelt sich um eine kleine Gruppe. Verstehen Sie diese Werte daher als Bandbreite, nicht als Prognose für Ihren Agenten.

Wenn das Guthaben aufgebraucht ist

Kunavo arbeitet mit Vorauszahlung: Jeder Aufruf wird aus dem Wallet bezahlt, und ein Agent, der arbeitet, während Sie schlafen, leert es, während Sie schlafen. Eine Anfrage, deren Kosten das Wallet nicht decken kann, wird auf beiden Übertragungswegen mit HTTP 402 und dem Code insufficient_balance abgelehnt; dafür wird nichts berechnet. Die Ablehnung erfolgt, bevor der Kontostand des Wallets null erreicht: Jede Anfrage reserviert zunächst ihre maximalen Kosten – den Prompt plus die größte zulässige Antwort. Je höher also die Ausgabebegrenzung ist, die ein Agent anfordert, desto früher werden seine Aufrufe abgelehnt. Der Fehler gibt an, wie viel gefehlt hat, in balance_usd und needed_usd.

OpenClaw leitet aus der Fehlermeldung ab, was ein 402 bedeutet. Nach den Regeln in OpenClaw 2026.9.8 ist die Ablehnung durch das Wallet ein Abrechnungsfehler, und die Failover-Referenz beschreibt die Folgen: Der Zugangsschlüssel wird zehn Minuten lang deaktiviert, der Lauf wechselt zum nächsten Modell in agents.defaults.model.fallbacks, und durch erneutes Aufladen wird die Sperrfrist nicht aufgehoben – nach einer Aufladung kann der Agent also bis zu deren Ablauf weiterhin keine Modelle unter kunavo/… nutzen. Die Ablehnung aufgrund des Monatslimits eines Schlüssels wird anders behandelt. In der Fehlermeldung wird ein Limit genannt, das zurückgesetzt wird; dieselben Regeln stufen dies als Ratenlimit ein: OpenClaw versucht es erneut und versetzt den Zugangsschlüssel anschließend zunächst für 30 Sekunden und höchstens für fünf Minuten in eine Abkühlphase. openclaw models status führt deaktivierte Zugangsschlüssel und den Zeitpunkt ihrer Reaktivierung auf.

Zwei Einstellungen schützen einen unbeaufsichtigten Agenten vor diesem Zustand, und sie erfüllen unterschiedliche Aufgaben:

• Automatisches Aufladen, unter Abrechnung. Speichern Sie eine Karte einmalig und legen Sie drei Werte fest: den Kontostand, unter dem Guthaben aufgeladen wird, den Betrag jeder Aufladung und ein monatliches Limit. Das Guthaben wird dann innerhalb von Sekunden nach einem Aufruf wieder aufgefüllt, durch den es unter den Schwellenwert fällt. Eine Anfrage, die eingeht, während das Guthaben noch nicht ausreicht, wartet auf diese Abbuchung und wird anschließend ausgeführt, statt abgelehnt zu werden. Ein 402 wird weiterhin zurückgegeben, wenn die Abbuchung nicht möglich ist — etwa weil die Karte abgelehnt wurde oder das Monatslimit erreicht ist — oder wenn eine Anfrage mehr Guthaben reserviert, als nach der Aufladung verfügbar ist. Dafür ist eine Karte oder Link erforderlich — Alipay, WeChat Pay, Pix und andere lokale Zahlungsmethoden können nicht automatisch belastet werden.
• Ein monatliches Limit für den Schlüssel, unter API-Schlüssel. Geben Sie dem Agenten einen eigenen Schlüssel und legen Sie den Höchstbetrag fest, den dieser Schlüssel in einem Kalendermonat ausgeben darf. Sobald dieser Betrag überschritten ist, werden seine Aufrufe mit einem 402 abgelehnt und es wird nichts berechnet, während Ihre anderen Schlüssel weiterhin funktionieren. Das ist die Obergrenze, die eine außer Kontrolle geratene Schleife braucht und die das Guthaben nicht bieten kann, da alle Schlüssel auf dasselbe Guthaben zugreifen.

Legen Sie den Schwellenwert fürs Aufladen höher fest als den Betrag, der für eine einzelne Anfrage reserviert wird. Bemessen Sie den Aufladebetrag am Tagesbedarf Ihres Agenten und nicht am Mindestbetrag: Die kleinste Aufladung beträgt $10, der zuvor genannte Median für einen Tag mit ständig aktivem Agenten $12.67. Die Limits für automatisches Aufladen finden Sie auf der Abrechnungsseite; den vollständigen Fehlerinhalt auf der Fehlerseite.

Verwandte Anleitungen

• Beste API für OpenClaw — Auswahl eines Anbieters und Modells für jede Aufgabenart.
• OpenClaw-Preise — die gesamten Betriebskosten: Software, Hosting, Modelle und Werkzeuge.
• OpenClaw mit mehreren Agenten und Modellen — jedem Agenten ein eigenes Modell zuweisen und die Kosten nach Route aufschlüsseln.
• Hermes im Vergleich zu OpenClaw — dieselbe Einrichtung für den anderen Agenten auf der Seite zu Hermes Agent.