OpenClaw

Une entrée models.providers dans ~/.openclaw/openclaw.json — baseUrl https://api.kunavo.com, api "anthropic-messages" — fait fonctionner un agent OpenClaw toujours actif avec Claude ; cacheRetention est défini à côté, car un point de terminaison Anthropic personnalisé ne reçoit aucun marqueur de cache tant que ce paramètre ne l’est pas.

// ~/.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" } },
      },
    },
  },
}

Étape par étape

1. Créez une clé sur /app/keys et copiez-la — elle n’est affichée qu’une seule fois.
2. Fournissez la clé à la passerelle : ajoutez KUNAVO_API_KEY=sk-kn-... à ~/.openclaw/.env ou exportez-la dans l’environnement dans lequel la passerelle démarre. À la lecture de la configuration, la valeur ${KUNAVO_API_KEY} du bloc est remplacée par celle qui s’y trouve.
3. Fusionnez le bloc dans ~/.openclaw/openclaw.json en conservant les fournisseurs, agents et canaux déjà présents. Le fichier est au format JSON5 ; les commentaires peuvent donc rester.
4. Exécutez openclaw config validate. OpenClaw refuse de démarrer si le fichier contient un paramètre qu’il ne reconnaît pas. Mieux vaut donc repérer une faute de frappe ici qu’au prochain redémarrage.
5. Exécutez openclaw models list --provider kunavo et vérifiez que les deux identifiants sont répertoriés. Si une passerelle en cours d’exécution n’a pas pris en compte la modification, exécutez openclaw gateway restart.
6. Ouvrez une nouvelle session avec /new — une session existante conserve le modèle qu’elle utilisait déjà —, envoyez deux messages, puis consultez /usage tokens : le second tour doit indiquer cacheRead.

Vérifié avec Référence des fournisseurs personnalisés d’OpenClaw le 5 octobre 2026. Les paramètres tiers évoluent ; si le nom d’un champ ne correspond plus à ce que vous voyez ici, cette page fait autorité, pas celle-ci.

Vérifiez avant de déboguer le client

Une requête suffit à déterminer si l’échec vient de l’endpoint, de la clé ou du fichier de configuration. Si cette requête renvoie du JSON, la même URL de base et la même clé fonctionnent dans 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"}]}'

Quel identifiant de modèle saisir dans le champ

Tous les modèles textuels sont accessibles sous forme d’identifiant de modèle — la liste à jour se trouve sur GET /v1/models, et le catalogue avec les prix sur la page des modèles. Les tarifs sont en USD par million de tokens, entrée / sortie.

Le protocole compatible OpenAI

La même clé permet d’accéder à toutes les autres familles de modèles via /v1/chat/completions. Enregistrez-la dans une seconde entrée de fournisseur pour que les deux protocoles restent distincts, puis référencez ses modèles sous la forme 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

Trois éléments diffèrent du bloc ci-dessus. L’URL de base conserve /v1, comme dans les exemples de fournisseurs personnalisés d’OpenClaw. api vaut openai-completions — valeur également utilisée par OpenClaw lorsqu’un fournisseur personnalisé fournit un baseUrl sans api. Enfin, maxTokens n’est plus facultatif en pratique : lorsque la limite de sortie d’un modèle est inconnue, OpenClaw n’envoie aucun plafond sur ce protocole et Kunavo termine alors une réponse Claude après 4 096 jetons.

Les identifiants Claude fonctionnent aussi ici ; c’est le protocole à utiliser si vous voulez une seule entrée pour tout. Deux éléments changent pour ces modèles : les niveaux de réflexion ne sont pas transmis à Claude via chat completions, et c’est Kunavo, et non OpenClaw, qui place les points de rupture du cache.

Mise en cache des prompts selon le protocole

Sur le protocole Anthropic, OpenClaw place lui-même les points de rupture du cache, mais, pour un point de terminaison personnalisé, il ne le fait que lorsque cacheRetention est défini. Sa documentation sur la mise en cache des prompts le précise : la valeur par défaut short est définie pour les seuls fournisseurs anthropic et anthropic-vertex, et toutes les autres routes de la famille Anthropic nécessitent une valeur explicite. Le /v1/messages de Kunavo transmet le corps tel qu’il a été envoyé, sans ajouter de point de rupture ; sans ces lignes dans la configuration, rien n’est mis en cache.

short demande une entrée de cinq minutes et long une entrée d’une heure. Kunavo transmet l’un ou l’autre marqueur et facture l’écriture au même tarif. Avant de planifier une fréquence en comptant sur la présence d’une entrée d’une heure à l’arrivée de la prochaine pulsation, vérifiez son comportement à partir de votre propre utilisation : un tour qui indique cacheRead a conservé son cache, tandis qu’un tour qui indique à nouveau cacheWrite ne l’a pas conservé. /usage tokens et /status affichent les deux compteurs.

Sur le protocole compatible OpenAI, c’est l’inverse. OpenClaw n’envoie aucun indice de mise en cache au point de terminaison proxy, et Kunavo place lui-même les points de rupture pour les modèles Claude — dans le prompt système, les définitions des outils et à la fin de la conversation — dès que le prompt est assez long pour être mis en cache. Aucun paramètre n’est nécessaire, et les modèles GPT sont mis en cache implicitement par leur fournisseur.

Quel que soit le côté qui place les points de rupture, la facture est la même. Sur Claude Sonnet 5 une lecture du cache coûte $0.14 par million de jetons, contre $1.40 pour une entrée fraîche, et une écriture dans le cache coûte $1.75 — la majoration d’écriture appliquée par Claude à l’entrée, facturée au même tarif lorsque l’entrée demande une durée de vie d’une heure. Une entrée dure cinq minutes et chaque lecture renouvelle sa durée ; le coût pour un agent dépend donc moins du modèle que du fait que sa prochaine requête arrive dans cette fenêtre. Les tarifs du cache de chaque modèle figurent sur la page consacrée à la mise en cache des prompts.

OpenClaw peut afficher les mêmes calculs en local. Son récapitulatif /usage cost et la ligne de coût dans /status nécessitent un objet cost pour chaque ligne de modèle ; sans cet objet, ils indiquent zéro, même si Kunavo facture normalement. Ces lignes sont générées à partir du catalogue en direct :

// 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 } },

Coût quotidien d’un agent toujours actif

Un agent OpenClaw est facturé même lorsque personne ne lui parle, à cause de la pulsation : un tour planifié de l’agent qui s’exécute toutes les 30 minutes par défaut, soit 48 par jour. Sauf indication contraire, il s’exécute dans la session principale et renvoie la conversation — la documentation de référence d’OpenClaw estime une telle exécution à environ 100 000 jetons, et à quelques milliers lorsqu’elle est isolée. Trente minutes dépassent la fenêtre de cache de cinq minutes ; chaque exécution est donc facturée pour l’intégralité de son prompt, au tarif d’entrée ou au tarif d’écriture, plus élevé, lorsqu’un point de rupture est placé. Le tableau chiffre une journée d’inactivité au tarif d’entrée, avec 5 000 jetons pour l’exécution isolée :

Le bloc ci-dessous correspond à un scénario peu coûteux de ce tableau : des pulsations sur Haiku, dans une session isolée, sans les fichiers d’initialisation de l’espace de travail et uniquement pendant les heures d’éveil. Tous les paramètres qu’il contient proviennent de la documentation de référence des pulsations d’OpenClaw. Un intervalle every plus long est l’autre levier, et "0m" désactive l’exécution récurrente.

// ~/.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" },
      },
    },
  },
}

Les heures pendant lesquelles l’agent travaille réellement représentent l’autre moitié de la facture, et c’est là que le cache fait la différence. Prenons 100 requêtes consécutives, chacune envoyant à nouveau un contexte de 100 000 jetons, auquel s’ajoutent 2 000 nouveaux jetons, et produisant 800 jetons en sortie. Sur Claude Sonnet 5, cela revient à environ $2.31 lorsque le contexte est lu depuis le cache, et à environ $14.84 lorsque le contexte est facturé comme une nouvelle entrée à chaque requête. Même travail, même modèle : la différence tient à la présence des points de rupture et au fait que les requêtes soient espacées de moins de cinq minutes.

Pour donner un ordre de grandeur, mesuré et non supposé : parmi les comptes Kunavo qui exécutent un agent en continu, le coût d’une journée active médiane est de $12.67, et celui d’une journée au 90e percentile est d’environ $163. Ces montants ont été facturés jusqu’au 5 octobre 2026, aux tarifs en vigueur chaque jour. Le groupe est restreint : voyez ces chiffres comme l’étendue de la fourchette, et non comme une prévision pour votre agent.

Quand le solde est épuisé

Kunavo fonctionne en prépaiement : chaque appel est payé depuis le portefeuille, et un agent qui travaille pendant que vous dormez le vide pendant que vous dormez. Une requête que le portefeuille ne peut pas couvrir est refusée avec HTTP 402 et le code insufficient_balance, quel que soit le protocole, et elle n’est pas facturée. Le refus survient avant que le solde du portefeuille n’atteigne zéro : chaque requête réserve d’abord son coût maximal, soit son prompt plus la réponse la plus longue qu’elle est autorisée à produire. Ainsi, plus le plafond de sortie demandé par un agent est élevé, plus tôt ses appels commencent à être refusés. L’erreur indique le montant manquant, en balance_usd et en needed_usd.

OpenClaw détermine la signification d’un 402 à partir de son message. Selon les règles d’OpenClaw 2026.9.8, le refus du portefeuille est un échec de facturation, et sa documentation de référence sur le basculement décrit la suite : l’identifiant d’accès est désactivé pendant dix minutes, l’exécution passe au modèle suivant dans agents.defaults.model.fallbacks, et la recharge ne met pas fin à cette période — l’agent peut donc continuer à ne pas utiliser les modèles kunavo/… après une recharge, jusqu’à la fin de cette période. Le refus lié à la limite mensuelle d’une clé est interprété différemment. Son message indique une limite qui est réinitialisée, ce que les mêmes règles traitent comme une limitation de débit : OpenClaw réessaie, puis met l’identifiant d’accès en pause pendant 30 secondes au départ, et jusqu’à cinq minutes au maximum. openclaw models status répertorie les identifiants d’accès désactivés et indique quand ils sont réactivés.

Deux paramètres empêchent un agent sans supervision d’en arriver là, et ils ont des fonctions différentes :

• Recharge automatique, sous Facturation. Enregistrez une carte une seule fois et définissez trois montants : le solde en dessous duquel le rechargement doit avoir lieu, le montant à ajouter à chaque fois et un plafond mensuel. Le portefeuille se recharge alors en quelques secondes dès qu’un appel fait passer son solde sous le seuil. Une requête reçue alors que le solde du portefeuille est encore insuffisant attend que le paiement soit effectué, puis est traitée au lieu d’être refusée. Un 402 est toujours renvoyé si le paiement ne peut pas être effectué — carte refusée, plafond mensuel atteint — ou si une requête réserve un montant supérieur au solde disponible après le rechargement. Cette fonctionnalité nécessite une carte ou Link ; Alipay, WeChat Pay, Pix et les autres moyens de paiement locaux ne peuvent pas être débités automatiquement.
• Une limite mensuelle pour la clé, sous Clés API. Attribuez à l’agent sa propre clé et définissez le montant maximal que cette clé peut dépenser au cours d’un mois civil. Au-delà de ce montant, ses appels sont refusés avec un 402 et aucun montant n’est débité, tandis que vos autres clés continuent de fonctionner. C’est le plafond qu’il faut pour contenir une boucle qui s’emballe, et que le portefeuille ne peut pas fournir, puisque toutes les clés utilisent le même portefeuille.

Définissez le seuil de recharge au-dessus du montant réservé pour une requête et choisissez le montant en fonction d’une journée d’utilisation de votre agent, pas du minimum : la recharge minimale est de $10, et la journée médiane d’un agent toujours actif indiquée plus haut coûte $12.67. Les limites de la recharge automatique sont indiquées sur la page de facturation, et le corps complet de l’erreur figure sur la page des erreurs.

Guides associés

• Meilleure API pour OpenClaw — choisir un fournisseur et un modèle pour chaque type de tâche.
• Tarification d’OpenClaw — le coût total d’exploitation : logiciel, hébergement, modèles et outils.
• OpenClaw avec plusieurs agents et modèles — acheminer chaque agent vers son propre modèle et ventiler les coûts par route.
• Hermes ou OpenClaw — et la même configuration pour l’autre agent, sur la page Hermes Agent.