OpenClaw con Gemini: configurazione del modello, chiavi API e verifica dei costi

OpenClaw raggiunge Gemini tramite il plugin google incluso: imposta GEMINI_API_KEY o GOOGLE_API_KEY, esegui openclaw onboard --auth-choice gemini-api-key, quindi imposta esplicitamente il modello — perché aggiungere l'autenticazione non modifica il modello predefinito. L'aspetto che la maggior parte degli articoli di configurazione trascura è che, con una chiave AI Studio, OpenClaw dispone di tre superfici Gemini separate, ciascuna con credenziali, endpoint e costi propri. (Vertex AI è un quarto percorso di credenziali separato tramite le Application Default Credentials di gcloud e non è trattato qui.) Far funzionare la chat non abilita la ricerca Gemini, e abilitare la ricerca Gemini può addebitare costi a un progetto Google che la route della chat non utilizza mai.

L'integrazione Gemini non richiede un'installazione separata. È inclusa direttamente in OpenClaw come plugin provider google incluso (plugin provider ufficiali, 21 settembre 2026), e OpenClaw è distribuito con licenza MIT e pubblicato come openclaw@2026.9.5 su npm, richiedendo Node >=24.16.0 <25 || >=26.1.0 (registro npm, 21 settembre 2026). Il software non costa nulla; tutto ciò che segue riguarda il costo delle chiavi.

Tre superfici Gemini, tre credenziali

Le regole di precedenza sono la parte utile. La ricerca web Gemini legge prima plugins.entries.google.config.webSearch.apiKey, poi GEMINI_API_KEY, quindi models.providers.google.apiKey, e il webSearch.baseUrl dedicato ha la precedenza su models.providers.google.baseUrl. OpenClaw inoltre non eredita qui gli header del provider del modello, perché "appartengono all'endpoint del provider del modello, che può differire dall'endpoint di ricerca web", e mantiene il controllo di Content-Type, x-goog-api-key e x-goog-api-client sulla richiesta di ricerca (documentazione della ricerca Gemini, 21 settembre 2026). Due route, deliberatamente indipendenti.

Prima di seguire un tutorial più vecchio: OpenClaw dichiara che "non offre una nuova configurazione OAuth per Gemini CLI o Antigravity OAuth", citando la fine dell'accesso consumer a Gemini CLI Login with Google il 18 giugno 2026 (documentazione del provider). Il post di Google del 19 maggio 2026 afferma che le estensioni Gemini CLI e Code Assist IDE smetteranno di servire gli abbonati Google AI Pro e Ultra e gli utenti gratuiti (blog degli sviluppatori Google). Entrambe le dichiarazioni riguardano la superficie CLI e IDE, non le chiavi API AI Studio — il percorso della chiave API è quello riportato di seguito.

Impostazione della chiave 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>

Il plugin incluso legge anche GEMINI_API_KEYS, GEMINI_API_KEY_1 e GEMINI_API_KEY_2 per la rotazione e OPENCLAW_LIVE_GEMINI_KEY come singolo override (plugin provider ufficiali, 21 settembre 2026). Queste sono documentate come variabili proprie del plugin google; il riferimento ai provider personalizzati non le elenca per un ID provider dichiarato autonomamente, che imposta la chiave tramite apiKey (l'espansione di $${ENV_VAR} è mostrata lì).

L'ultima riga è più importante di quanto sembri. openclaw configure "conserva un agents.defaults.model.primary esistente quando aggiungi o riautentichi un provider", e openclaw models auth login fa lo stesso a meno che tu non passi --set-default (regole rapide). Autenticare Gemini e continuare a ricevere risposte dal vecchio modello è un comportamento previsto, non un bug.

Non copiare un ID modello da un tutorial, incluso questo. Con una chiave configurata, OpenClaw aggiorna il catalogo dei modelli di testo di Google AI Studio dall'API Gemini models.list, quindi le nuove varianti compaiono senza una release di OpenClaw — e le stesse pagine di OpenClaw non concordano sull'ID di esempio, indicando google/gemini-3.5-flash in un punto, google/gemini-3.1-flash e google/gemini-3.1-pro-preview in un altro, e impostando lo strumento di ricerca su gemini-3.6-flash. L'elenco attivo è l'unica autorità. OpenClaw normalizza alcuni riferimenti legacy — google/gemini-3.1-pro è "accettato e normalizzato" in google/gemini-3.1-pro-preview (plugin provider ufficiali) — e google/gemini-3-pro-preview "è stato ritirato il 2026-03-09", con google/gemini-3.1-pro-preview indicato come sostituto (documentazione del provider, 21 settembre 2026).

Cosa addebita realmente una chiave API Gemini

Token e grounding della ricerca sono due voci separate, e la pagina di Google a prima vista sembra presentarli come una sola. Le tariffe Gemini Developer API del livello Standard sono espresse per 1M token, secondo la pagina dei prezzi di Google (ultimo aggiornamento 16 settembre 2026, consultata il 21 settembre 2026):

Leggi due volte l'ultima colonna. Il modello Gemini predefinito per la ricerca web di OpenClaw è gemini-3.6-flash, un modello Gemini 3.x il cui grounding è "Non disponibile" nel livello gratuito di Google — quindi la configurazione di ricerca Gemini pronta all'uso richiede un progetto con fatturazione, anche se i token dello stesso modello sono gratuiti. Anche le unità differiscono: OpenClaw stesso osserva che "il grounding di Gemini 3 viene addebitato per query di ricerca, mentre il grounding di Gemini 2.5 viene addebitato per prompt", e Google aggiunge che una richiesta "può comportare una o più query a Google Search. Ti verrà addebitata ogni singola query di ricerca eseguita". Il grounding si aggiunge al costo dei token — "I costi per Gemini si applicano sempre" (entrambe le citazioni provengono dalla stessa pagina dei prezzi). A titolo illustrativo, un mese con 6.500 query di ricerca Gemini 3.x addebita 1.500 di esse a $14 per 1.000, cioè $21,00 di sole tariffe di ricerca, prima dei token.

Altri due elementi dalla stessa pagina: il livello a pagamento aggiunge la memorizzazione nella cache del contesto e una Batch API con una riduzione dei costi del 50%, e modifica il punto sull'utilizzo dei dati — i contenuti del livello gratuito sono "utilizzati per migliorare i nostri prodotti", mentre quelli a pagamento no, aspetto importante per un assistente sempre attivo. Gemini è inoltre solo uno dei provider di ricerca di OpenClaw; DuckDuckGo ("Nessuno (senza chiave)"), SearXNG ("Nessuno (self-hosted)") e Parallel Search (Free) ("Nessuno (free Search MCP)") sono elencati come opzioni senza chiave nella tabella dei provider di ricerca web (ricerca web, 21 settembre 2026), quindi "mi serve davvero il grounding Gemini?" è una prima domanda ragionevole.

Instradare la chat Gemini tramite un gateway compatibile con OpenAI

Il riferimento ai provider personalizzati di OpenClaw indica di usare voci models.providers.<id> esplicite "solo quando vuoi sovrascrivere l'URL di base, gli header o l'elenco dei modelli predefiniti", e il riferimento alla configurazione del gateway elenca undici valori api: openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, pi-messages e azure-openai-responses. Lo schema di configurazione alla v2026.9.7 accetta un dodicesimo valore, google-interactions, aggiunto il 25 settembre 2026. Il riferimento non lo elenca ancora, ma la pagina del provider Google di OpenClaw lo documenta come alternativa opzionale al trasporto predefinito google-generative-ai, usando la Gemini Interactions API sotto https://generativelanguage.googleapis.com/v1beta. I modelli Gemini di Kunavo sono raggiungibili tramite la sua superficie compatibile con OpenAI a POST /v1/chat/completions (endpoint chat), e Kunavo non pubblica alcun endpoint generativelanguage, v1beta o Interactions — quindi nessuno degli adattatori Google lo raggiunge, e la route raggiungibile è un ID provider separato, mai un plugin google reindirizzato.

{
  "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"
      }
    }
  }
}

Quattro dettagli sono fondamentali. Lo slug usa i trattini — l'ID di Kunavo è gemini-3-8-flash, mentre quelli di Google e OpenClaw usano i punti, e sono stringhe diverse. contextWindow viene dichiarato perché un modello personalizzato privo di metadati del contesto ricade su un budget di 200.000 token, sprecando gran parte della finestra che il catalogo di Kunavo registra qui (1.048.576 token — metadati di Kunavo, non un limite pubblicato da Google). input indica le immagini perché OpenClaw imposta per impostazione predefinita un modello personalizzato come solo testuale. E cost viene omesso, quindi la stima locale di OpenClaw su questa route ricade su zero: una lettura di $0 indica metadati mancanti, non inferenza gratuita.

Ciò a cui si rinuncia con questa route è documentato, non ipotizzato. Con api: "openai-completions" verso un host che non è quello di OpenAI, OpenClaw forza compat.supportsDeveloperRole: false e salta la preparazione nativa delle richieste — niente service_tier, niente store di Responses o Completions, niente suggerimenti per la cache dei prompt, niente preparazione del payload compatibile con il ragionamento (provider personalizzati). Anche gli extra specifici di Gemini restano esclusi: params.cachedContent è documentato per le esecuzioni Gemini dirette, le variabili di rotazione delle chiavi sono funzioni del plugin e la mappatura thinkingLevel / thinkingBudget di OpenClaw è descritta per il provider google — non è stato verificato da questa pagina se sopravviva a una route tramite gateway.

Kunavo non fornisce alcun modello di embedding né modelli di sintesi o riconoscimento vocale. I contratti di embedding e voce del plugin google restano quindi su una chiave Google, indipendentemente da come viene instradata la chat.

Per le capacità, presta attenzione a chi stai prendendo in parola. L'attuale pagina dei modelli di Google non visualizza più i limiti di token per modello, quindi una cifra relativa al contesto citata altrove è una copia di una fonte precedente. Il catalogo di Kunavo segnala visione, chiamate di funzione, streaming e contesto esteso nelle sue voci Gemini, e il ragionamento in tutte tranne gemini-2-5-flash. Ogni affermazione è circoscritta a chi l'ha pubblicata — verifica prima le chiamate agli strumenti sulla tua attività.

Calcola il prezzo del modello che hai scelto

Per modello, rispetto al livello Standard di Google, perché oggi la versione a livello familiare di questo confronto è falsa:

Le tariffe di Kunavo provengono dal catalogo attivo e quelle di Google dalla pagina dei prezzi consultata il 21 settembre 2026; la finestra introduttiva termina il 31 dicembre 2026, dopodiché il confronto Flash si inverte nuovamente.

Una stima esemplificativa, che è aritmetica dei token e non un'attività OpenClaw misurata né un limite di fatturazione. Supponiamo una settimana di lavoro dell'assistente con 4.000.000 di token di input non memorizzati nella cache e 150.000 token di output, senza caching e senza ricerca. Su Gemini 3.8 Flash alle tariffe di Kunavo sono $2,49; la stessa aritmetica alle tariffe Flash introduttive di Google è $3,56, che sale a $7,13 alla tariffa del 2027. Esegui gli stessi volumi su Gemini 3.6 Flash in Kunavo e ottieni $4,99 — sopra la cifra introduttiva di Google, ed è esattamente per questo che conta l'ID del modello, non il nome del provider.

L'importo del catalogo di Kunavo è un minimo di fatturazione, non un limite massimo: quando l'upstream comunica il proprio addebito, la fattura è il maggiore tra il costo del catalogo e il costo upstream moltiplicato per il markup applicabile. Gli addebiti per la cache, il grounding della ricerca e l'hosting sono esclusi da questo esempio, e la ricarica minima è $10 di credito prepagato — un minimo di finanziamento, non un costo per attività né un abbonamento. Consulta i dettagli della fatturazione e i prezzi di OpenClaw per il costo operativo completo.

Verifica con una richiesta, poi leggi entrambi i registri

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 legge l'inventario pubblicato e openclaw models status mostra il valore predefinito risolto e lo stato dell'autenticazione; nessuno dei due dimostra che un'attività a pagamento funzioni, e openclaw models set su un provider noto salva un modello non presente nel catalogo con solo un avviso. openclaw doctor --json --severity-min info mostra anche i modelli attivi che il catalogo locale non può confermare (riferimento CLI). La singola richiesta sopra è la prima prova che comporta un costo.

Esegui il triage in base al codice di stato. OpenClaw documenta la firma model_not_found per un server locale compatibile con OpenAI e i tre campi che indica sono gli stessi tre impostati da una voce di provider personalizzata: verifica che baseUrl includa /v1, che api sia "openai-completions" per un backend /v1/chat/completions e che models[].id sia l'ID semplice locale al provider, con il prefisso del provider usato solo al momento della selezione (risoluzione dei problemi). Con Kunavo, il controllo che indica che l'URL di base è corretto è una richiesta non autenticata a un percorso API reale: GET https://api.kunavo.com/v1/models risponde 401 con un corpo authentication_error, il che significa che l'URL è corretto e che manca la chiave. L'host semplice e il percorso /v1 semplice non sono percorsi API e rispondono con HTML, quindi un client puntato su uno dei due fallirà prima ancora di raggiungere un modello (verificato il 21 settembre 2026). Un 403 è quello da fermare e leggere: OpenClaw avverte che "può provenire da un livello di sicurezza upstream come una CDN, un WAF, una regola di gestione dei bot o un reverse proxy" e che un curl minimo riuscito non garantisce che le richieste reali nello stile degli SDK superino lo stesso livello. Consulta modello non trovato e chiave API Gemini non funzionante per le versioni più lunghe.

Per la route nativa, inizia dalle note di Kunavo sulla chiave API Gemini e da Google AI Studio; per la route tramite gateway, crea una chiave in Chiavi API e apri un account Kunavo, quindi segui la procedura guidata sui provider personalizzati in migliore API per OpenClaw. Mantieni disponibile la route funzionante mentre esegui i test.

Quale route prevale quando

Se stai ancora scegliendo un provider anziché configurarne uno, prezzi dell'API Gemini e API compatibile con OpenAI coprono le due metà di questa decisione.

Domande frequenti

Recuperato per questa pagina il 21 settembre 2026: la documentazione di OpenClaw relativa al provider Google, ai plugin provider ufficiali, alla ricerca Gemini, alla ricerca web, ai provider personalizzati (sia i concetti sia il riferimento del gateway), alle regole rapide, ai modelli CLI e alla risoluzione dei problemi; la pagina dei prezzi dell'API Gemini di Google (ultimo aggiornamento 16 settembre 2026), la pagina dei modelli, la pagina sul grounding con Google Search e il post del blog degli sviluppatori del 19 maggio 2026; la voce del registro npm per openclaw; e il catalogo di Kunavo. Il 1 ottobre 2026 i valori api del provider personalizzato sono stati ricontrollati rispetto al riferimento del gateway, alla pagina del provider Google, allo schema di configurazione di OpenClaw e al trasporto Interactions nel suo codice sorgente alla v2026.9.7. L'unica richiesta live effettuata per questa pagina è stata una GET non autenticata a /v1/models di Kunavo, per registrare il 401 descritto sopra. Nulla di quanto riportato è stato testato a runtime con un'installazione di OpenClaw, sull'endpoint di Kunavo o su quello di Google; ogni cifra in dollari è aritmetica illustrativa basata sulle tariffe pubblicate.