OpenClaw avec Gemini : configuration du modèle, clés API et vérification des coûts

OpenClaw accède à Gemini via son plugin google intégré : définissez GEMINI_API_KEY ou GOOGLE_API_KEY, exécutez openclaw onboard --auth-choice gemini-api-key, puis définissez explicitement le modèle — car l'ajout d'une authentification ne modifie pas votre modèle par défaut. Ce que la plupart des articles de configuration oublient, c'est qu'avec une clé AI Studio, OpenClaw propose trois surfaces Gemini distinctes, chacune avec ses propres identifiants, endpoint et facturation. (Vertex AI constitue une quatrième voie d'identification distincte via les identifiants Application Default Credentials de gcloud, et n'est pas couvert ici.) Faire fonctionner le chat n'active pas la recherche Gemini, et activer la recherche Gemini peut imputer des frais à un projet Google que votre route de chat ne touche jamais.

L'intégration Gemini ne nécessite pas une installation distincte. Elle est incluse dans OpenClaw lui-même sous la forme du plugin fournisseur google intégré (plugins fournisseurs officiels, 21 septembre 2026), et OpenClaw est distribué sous licence MIT et publié comme openclaw@2026.9.5 sur npm, avec Node >=24.16.0 <25 || >=26.1.0 requis (registre npm, 21 septembre 2026). Le logiciel est gratuit ; tout ce qui suit concerne le coût des clés.

Trois surfaces Gemini, trois identifiants

Les règles de priorité sont la partie utile. La recherche Web Gemini lit d'abord plugins.entries.google.config.webSearch.apiKey, puis GEMINI_API_KEY, puis models.providers.google.apiKey, et le webSearch.baseUrl dédié est prioritaire sur models.providers.google.baseUrl. OpenClaw refuse également d'hériter ici des en-têtes du fournisseur de modèle, car ils « appartiennent à l'endpoint du fournisseur de modèle, qui peut différer de l'endpoint de recherche Web », et conserve la gestion de Content-Type, x-goog-api-key et x-goog-api-client dans la requête de recherche (documentation de la recherche Gemini, 21 septembre 2026). Deux routes, délibérément indépendantes.

Avant de suivre un ancien tutoriel : OpenClaw indique qu'il « ne propose pas de nouvelle configuration OAuth Gemini CLI ou OAuth Antigravity », en citant la fin de la connexion Gemini CLI grand public avec accès Google le 18 juin 2026 (documentation du fournisseur). La propre publication de Google du 19 mai 2026 indique que Gemini CLI et les extensions IDE Code Assist cessent de servir les abonnés Google AI Pro et Ultra ainsi que les utilisateurs gratuits (blog des développeurs Google). Les deux déclarations concernent l'interface CLI et IDE, et non les clés API AI Studio — la voie par clé API est celle présentée ci-dessous.

Définition de la clé API Gemini

# The bundled google plugin reads either name.
export GEMINI_API_KEY="AIza..."   # or GOOGLE_API_KEY

openclaw onboard --auth-choice gemini-api-key

# Auth alone does not change the default model — set it on purpose.
openclaw models list --provider google
openclaw models set google/<id-from-that-list>

Le plugin intégré lit également GEMINI_API_KEYS, GEMINI_API_KEY_1 et GEMINI_API_KEY_2 pour la rotation, ainsi que OPENCLAW_LIVE_GEMINI_KEY comme remplacement unique (plugins fournisseurs officiels, 21 septembre 2026). Ces variables sont documentées comme appartenant au plugin google ; la référence des fournisseurs personnalisés ne les répertorie pas pour un identifiant de fournisseur que vous déclarez vous-même, lequel définit sa clé via apiKey ($${ENV_VAR} expansion y est présentée).

La dernière ligne est plus importante qu'il n'y paraît. openclaw configure « conserve un agents.defaults.model.primary existant lorsque vous ajoutez ou réauthentifiez un fournisseur », et openclaw models auth login fait de même, sauf si vous transmettez --set-default (règles rapides). S'authentifier auprès de Gemini tout en continuant à obtenir des réponses de l'ancien modèle est donc un comportement attendu, pas un bug.

Ne copiez pas un identifiant de modèle depuis un tutoriel, y compris celui-ci. Avec une clé configurée, OpenClaw actualise le catalogue des modèles de texte d'AI Studio de Google depuis l'API Gemini models.list, de sorte que les nouvelles variantes apparaissent sans nouvelle version d'OpenClaw — et les propres pages d'OpenClaw ne concordent pas sur l'identifiant d'exemple, en nommant google/gemini-3.5-flash à un endroit, google/gemini-3.1-flash et google/gemini-3.1-pro-preview à un autre, et en définissant gemini-3.6-flash par défaut pour l'outil de recherche. La liste en temps réel fait seule autorité. OpenClaw normalise bien certaines anciennes références — google/gemini-3.1-pro est « accepté et normalisé » vers google/gemini-3.1-pro-preview (plugins fournisseurs officiels) — et google/gemini-3-pro-preview « a été retiré le 2026-03-09 », google/gemini-3.1-pro-preview étant nommé comme son remplacement (documentation du fournisseur, 21 septembre 2026).

Ce qu'une clé API Gemini facture réellement

Les jetons et l'ancrage de recherche sont deux postes distincts, même si la page de Google donne l'impression d'un seul élément au premier regard. Les tarifs de l'API Gemini Developer au niveau Standard sont calculés par million de jetons, d'après la page tarifaire de Google (dernière mise à jour le 16 septembre 2026, consultée le 21 septembre 2026) :

Lisez la dernière colonne deux fois. Le modèle de recherche Web Gemini par défaut d'OpenClaw est gemini-3.6-flash, un modèle Gemini 3.x dont l'ancrage est « Non disponible » au niveau gratuit de Google — la configuration de recherche Gemini prête à l'emploi nécessite donc un projet facturé, même si les jetons de ce même modèle sont gratuits. Les unités diffèrent également : OpenClaw indique lui-même que « l'ancrage Gemini 3 est facturé par requête de recherche, tandis que l'ancrage Gemini 2.5 est facturé par invite », et Google ajoute qu'une requête « peut entraîner une ou plusieurs requêtes vers Google Search. Vous serez facturé pour chaque requête de recherche individuelle effectuée ». L'ancrage s'ajoute au coût des jetons — « les coûts de Gemini s'appliquent toujours » (les deux citations proviennent de la même page tarifaire). À titre d'illustration, un mois comprenant 6 500 requêtes de recherche Gemini 3.x en facture 1 500 à $14 par tranche de 1 000, soit $21.00 de frais de recherche seuls, avant tout jeton.

Deux autres éléments de la même page : le niveau payant ajoute la mise en cache du contexte et une API Batch avec une réduction de coût de 50 %, et inverse l'élément relatif à l'utilisation des données — le contenu du niveau gratuit est « utilisé pour améliorer nos produits », tandis que le contenu payant ne l'est pas, ce qui compte pour un assistant toujours actif. Gemini n'est également que l'un des fournisseurs de recherche d'OpenClaw ; DuckDuckGo (« Aucun (sans clé) »), SearXNG (« Aucun (auto-hébergé) ») et Parallel Search (Free) (« Aucun (Search MCP gratuit) ») sont répertoriés comme options sans clé dans le tableau des fournisseurs de recherche Web (recherche Web, 21 septembre 2026). La question « ai-je vraiment besoin de l'ancrage Gemini ? » est donc une première question légitime à se poser.

Acheminement du chat Gemini via une passerelle compatible avec OpenAI

La référence des fournisseurs personnalisés d'OpenClaw indique d'utiliser des entrées models.providers.<id> explicites « uniquement lorsque vous souhaitez remplacer l'URL de base, les en-têtes ou la liste des modèles par défaut », et la référence de configuration des passerelles répertorie onze valeurs api : openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, pi-messages et azure-openai-responses. Le schéma de configuration à la v2026.9.7 en accepte une douzième, google-interactions, ajoutée le 25 septembre 2026. La référence ne la répertorie pas encore, mais la page du fournisseur Google d'OpenClaw la documente comme alternative facultative au transport google-generative-ai par défaut, en utilisant l'API Interactions de Gemini sous https://generativelanguage.googleapis.com/v1beta. Les modèles Gemini de Kunavo sont accessibles via sa surface compatible avec OpenAI à POST /v1/chat/completions (endpoint de chat), et Kunavo ne publie aucun generativelanguage, v1beta ni endpoint Interactions — aucun des adaptateurs Google ne peut donc l'atteindre, et la route accessible est un identifiant de fournisseur distinct, jamais un plugin google redirigé.

{
  "models": {
    "mode": "merge",
    "providers": {
      "kunavo": {
        "baseUrl": "https://api.kunavo.com/v1",
        "apiKey": "${KUNAVO_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gemini-3-8-flash",
            "name": "Gemini 3.8 Flash",
            "input": [
              "text",
              "image"
            ],
            "contextWindow": 1048576,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "kunavo/gemini-3-8-flash"
      }
    }
  }
}

Quatre détails y sont déterminants. Le slug utilise des tirets — l'identifiant de Kunavo est gemini-3-8-flash, tandis que ceux de Google et d'OpenClaw utilisent des points ; ce sont des chaînes différentes. contextWindow est déclaré, car un modèle personnalisé sans métadonnées de contexte revient à un budget de 200 000 jetons, ce qui gaspille la majeure partie de la fenêtre enregistrée dans le catalogue de Kunavo ici (1 048 576 jetons — métadonnées de Kunavo, et non une limite publiée par Google). input indique la prise en charge des images, car OpenClaw définit par défaut un modèle personnalisé comme étant limité au texte. Et cost est omis, de sorte que l'estimation locale d'OpenClaw revient à zéro sur cette route : un affichage de $0 signifie que les métadonnées sont absentes, pas que l'inférence est gratuite.

Ce que cette route abandonne est documenté, et non supposé. Avec api: "openai-completions" face à un hôte qui n'est pas celui d'OpenAI, OpenClaw force compat.supportsDeveloperRole: false et ignore la mise en forme native des requêtes — pas de service_tier, pas de store Responses ou Completions, pas d'indications de mise en cache des invites, pas de mise en forme de la charge utile compatible avec le raisonnement (fournisseurs personnalisés). Les fonctionnalités supplémentaires propres à Gemini restent également derrière : params.cachedContent est documenté pour les exécutions Gemini directes, les variables de rotation des clés sont des fonctionnalités du plugin, et la correspondance thinkingLevel / thinkingBudget d'OpenClaw est décrite pour le fournisseur google — cette correspondance subsiste ou non via une route de passerelle, ce que cette page n'a pas vérifié.

Kunavo ne fournit aucun modèle d'embedding, ni modèle de synthèse ou de reconnaissance vocale. Les contrats d'embedding et de traitement vocal du plugin google restent donc associés à une clé Google, quelle que soit la manière dont le chat est acheminé.

Concernant les capacités, faites attention à la source de l'affirmation. La page actuelle des modèles de Google n'affiche plus les limites de jetons par modèle ; tout chiffre de contexte cité ailleurs provient donc d'une copie d'une ancienne source. Le catalogue de Kunavo indique la vision, l'appel de fonctions, le streaming et le contexte long pour ses modèles Gemini, ainsi que la réflexion pour tous sauf gemini-2-5-flash. Chaque affirmation est limitée à son éditeur — vérifiez d'abord les appels d'outils sur votre propre tâche.

Tarifez le modèle réellement choisi

Par modèle, par rapport au niveau Standard de Google, car la comparaison à l'échelle de toute la famille est fausse aujourd'hui :

Les tarifs de Kunavo proviennent du catalogue en temps réel et ceux de Google de la page tarifaire consultée le 21 septembre 2026 ; la période d'introduction se termine le 31 décembre 2026, après quoi la comparaison Flash s'inverse à nouveau.

Une estimation détaillée, qui est un calcul de jetons et non une tâche OpenClaw mesurée ni un plafond de facture. Supposons une semaine de travail d'assistant envoyant 4 000 000 de jetons d'entrée non mis en cache et recevant 150 000 jetons de sortie, sans mise en cache ni recherche. Avec Gemini 3.8 Flash aux tarifs de Kunavo, cela représente $2.49 ; le même calcul au tarif Flash d'introduction de Google donne $3.56, montant qui passe à $7.13 au tarif de 2027. Appliquez les mêmes volumes à Gemini 3.6 Flash chez Kunavo et vous obtenez $4.99 — davantage que le montant calculé au tarif d'introduction de Google, ce qui explique précisément pourquoi l'identifiant du modèle, et non le nom du fournisseur, est le facteur décisif.

Le montant du catalogue de Kunavo constitue un plancher de facturation, et non un plafond : lorsque l'amont communique son coût, la facture correspond au montant le plus élevé entre le coût du catalogue et le coût amont multiplié par la majoration applicable. Les frais de cache, l'ancrage de recherche et l'hébergement ne sont pas inclus dans cet exemple, et le rechargement minimal est de $10 de crédit prépayé — un minimum de financement, et non des frais de tâche ou un abonnement. Consultez les détails de facturation et la tarification d'OpenClaw pour connaître la facture d'exploitation complète.

Vérifiez avec une requête, puis consultez les deux registres

openclaw config validate
openclaw gateway restart
openclaw models list --provider kunavo
openclaw infer model run --model kunavo/gemini-3-8-flash --prompt "hi" --json

openclaw models list lit l'inventaire publié et openclaw models status affiche l'état résolu des valeurs par défaut et de l'authentification ; aucun des deux ne prouve qu'une tâche payante fonctionne, et openclaw models set auprès d'un fournisseur connu enregistre un modèle absent du catalogue avec un simple avertissement. openclaw doctor --json --severity-min info expose également les modèles actifs que le catalogue local ne peut pas confirmer (référence CLI). La requête unique ci-dessus est la première preuve qui coûte de l'argent.

Faites le tri par code d'état. OpenClaw documente la signature model_not_found pour un serveur local compatible avec OpenAI, et les trois champs qu'il nomme sont les trois mêmes que définit une entrée de fournisseur personnalisé : vérifiez que baseUrl inclut /v1, que api vaut "openai-completions" pour un backend /v1/chat/completions, et que models[].id est l'identifiant local nu du fournisseur, le préfixe du fournisseur n'étant utilisé qu'au moment de la sélection (dépannage). Avec Kunavo, la vérification qui indique que l'URL de base est correcte est une requête non authentifiée vers un véritable chemin d'API : GET https://api.kunavo.com/v1/models renvoie 401 avec un corps authentication_error, ce qui signifie que l'URL est correcte et que la clé ne l'est pas. L'hôte nu et le chemin /v1 nu ne sont pas des chemins d'API et renvoient du HTML ; un client pointant vers l'un ou l'autre échouera donc avant même d'atteindre un modèle (vérifié le 21 septembre 2026). Un 403 est le cas qui impose de s'arrêter et de lire : OpenClaw avertit qu'il « peut provenir d'une couche de sécurité en amont telle qu'un CDN, un WAF, une règle de gestion des bots ou un proxy inverse », et qu'un curl minimal réussi ne garantit pas que les véritables requêtes de type SDK franchiront la même couche. Consultez modèle introuvable et la clé API Gemini ne fonctionne pas pour les versions détaillées.

Pour la route native, commencez par les notes de Kunavo sur la clé API Gemini et Google AI Studio ; pour la route via passerelle, créez une clé dans Clés API et ouvrez un compte Kunavo, puis suivez le guide des fournisseurs personnalisés dans meilleure API pour OpenClaw. Gardez votre route fonctionnelle disponible pendant les tests.

Quelle route l'emporte selon le cas

Si vous choisissez encore un fournisseur plutôt que de le configurer, Tarification de l'API Gemini et API compatible avec OpenAI couvrent les deux volets de cette décision.

Questions fréquentes

Récupéré pour cette page le 21 septembre 2026 : la documentation d'OpenClaw relative aux fournisseurs Google, aux plugins fournisseurs officiels, à la recherche Gemini, à la recherche Web, aux fournisseurs personnalisés (à la fois les concepts et la référence de passerelle), aux règles rapides, aux modèles CLI et au dépannage ; la page tarifaire de l'API Gemini de Google (dernière mise à jour le 16 septembre 2026), sa page des modèles, sa page sur l'ancrage avec Google Search et sa publication du 19 mai 2026 sur le blog des développeurs ; l'entrée du registre npm pour openclaw ; et le catalogue de Kunavo. Le 1er octobre 2026, les valeurs api des fournisseurs personnalisés ont été revérifiées par rapport à la référence de passerelle, à la page du fournisseur Google, ainsi qu'au schéma de configuration et au transport Interactions d'OpenClaw dans son code source à la v2026.9.7. La seule requête en temps réel effectuée pour cette page était un GET non authentifié vers /v1/models de Kunavo, afin d'enregistrer le 401 décrit ci-dessus. Rien ici n'a été testé en conditions d'exécution avec une installation d'OpenClaw, sur l'endpoint de Kunavo ou sur ceux de Google ; chaque montant en dollars est un calcul illustratif fondé sur les tarifs publiés.