Providers

Google (Gemini)

Il plugin Google fornisce accesso ai modelli Gemini tramite Google AI Studio, oltre a generazione di immagini, comprensione di contenuti multimediali (immagini/audio/video), sintesi vocale e ricerca web tramite Gemini Grounding.

Provider: google
Autenticazione: GEMINI_API_KEY o GOOGLE_API_KEY
API: API Google Gemini
Opzione di runtime: agentRuntime.id: "google-gemini-cli" riutilizza OAuth della CLI Gemini mantenendo canonici i riferimenti ai modelli come google/*.

Per iniziare

Scegli il metodo di autenticazione preferito e segui i passaggi di configurazione.

Chiave API

Ideale per: accesso standard all'API Gemini tramite Google AI Studio.

Esegui la configurazione iniziale

bash

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

In alternativa, passa direttamente la chiave:

bash

openclaw onboard --non-interactive \  --mode local \  --auth-choice gemini-api-key \  --gemini-api-key "$GEMINI_API_KEY"

Imposta un modello predefinito

json5

{  agents: {    defaults: {      model: { primary: "google/gemini-3.1-pro-preview" },    },  },}

Verifica che il modello sia disponibile

bash

openclaw models list --provider google

CLI Gemini (OAuth)

Ideale per: riutilizzare un accesso esistente alla CLI Gemini tramite OAuth PKCE anziché una chiave API separata.

Installa la CLI Gemini

Il comando locale gemini deve essere disponibile in PATH.

bash

# Homebrewbrew install gemini-cli # oppure npmnpm install -g @google/gemini-cli

OpenClaw supporta sia le installazioni tramite Homebrew sia quelle globali tramite npm, incluse le comuni strutture Windows/npm.

Accedi tramite OAuth

bash

openclaw models auth login --provider google-gemini-cli --set-default

Verifica che il modello sia disponibile

bash

openclaw models list --provider google

Modello predefinito: google/gemini-3.1-pro-preview
Runtime: google-gemini-cli
Alias: gemini-cli

L'ID del modello Gemini API di Gemini 3.1 Pro è gemini-3.1-pro-preview. OpenClaw accetta la forma abbreviata google/gemini-3.1-pro come alias pratico e la normalizza prima delle chiamate al provider.

Variabili d'ambiente:

OPENCLAW_GEMINI_OAUTH_CLIENT_ID / GEMINI_CLI_OAUTH_CLIENT_ID
OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET / GEMINI_CLI_OAUTH_CLIENT_SECRET

I riferimenti ai modelli google-gemini-cli/* sono alias di compatibilità legacy. Le nuove configurazioni devono usare riferimenti ai modelli google/* insieme al runtime google-gemini-cli quando si desidera l'esecuzione locale tramite la CLI Gemini.

Funzionalità

Funzionalità	Supportata
Completamenti di chat	Sì
Generazione di immagini	Sì
Generazione musicale	Sì
Sintesi vocale	Sì
Voce in tempo reale	Sì (Google Live API)
Comprensione delle immagini	Sì
Trascrizione audio	Sì
Comprensione dei video	Sì
Ricerca web (Grounding)	Sì
Pensiero/ragionamento	Sì (Gemini 2.5+ / Gemini 3+)
Modelli Gemma 4	Sì

Ricerca web

Il provider di ricerca web gemini incluso usa il Grounding con Google Search di Gemini. Configura una chiave di ricerca dedicata in plugins.entries.google.config.webSearch, oppure consentigli di riutilizzare models.providers.google.apiKey dopo GEMINI_API_KEY:

json5

{  plugins: {    entries: {      google: {        config: {          webSearch: {            apiKey: "AIza...", // facoltativo se è impostato GEMINI_API_KEY o models.providers.google.apiKey            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // usa come ripiego models.providers.google.baseUrl            model: "gemini-2.5-flash",          },        },      },    },  },}

L'ordine di precedenza delle credenziali è: webSearch.apiKey dedicata, quindi GEMINI_API_KEY, infine models.providers.google.apiKey. webSearch.baseUrl è facoltativo ed è destinato ai proxy degli operatori o agli endpoint compatibili con l'API Gemini; se omesso, la ricerca web di Gemini riutilizza models.providers.google.baseUrl. Consulta Ricerca Gemini per il comportamento dello strumento specifico del provider.

Tip

I modelli Gemini 3 usano thinkingLevel anziché thinkingBudget. OpenClaw associa i controlli di ragionamento di Gemini 3, Gemini 3.1 e degli alias gemini-*-latest a thinkingLevel, in modo che le esecuzioni predefinite/a bassa latenza non inviino valori thinkingBudget disabilitati.

/think adaptive mantiene la semantica di pensiero dinamico di Google anziché scegliere un livello OpenClaw fisso. Gemini 3 e Gemini 3.1 omettono un thinkingLevel fisso affinché Google possa scegliere il livello; Gemini 2.5 invia il valore sentinella dinamico di Google thinkingBudget: -1.

I modelli Gemma 4 (ad esempio gemma-4-26b-a4b-it) supportano la modalità di pensiero. OpenClaw converte thinkingBudget in un valore Google thinkingLevel supportato per Gemma 4. Impostando il pensiero su off, questo rimane disabilitato anziché essere associato a MINIMAL.

Gemini 2.5 Pro funziona solo in modalità di pensiero e rifiuta un valore esplicito thinkingBudget: 0; OpenClaw rimuove tale valore dalle richieste per Gemini 2.5 Pro anziché inviarlo.

Generazione di immagini

Il provider google incluso per la generazione di immagini usa come valore predefinito google/gemini-3.1-flash-image-preview.

Supporta anche google/gemini-3-pro-image-preview
Generazione: fino a 4 immagini per richiesta
Modalità di modifica: abilitata, fino a 5 immagini di input
Controlli geometrici: size, aspectRatio e resolution

Per usare Google come provider di immagini predefinito:

json5

{  agents: {    defaults: {      imageGenerationModel: {        primary: "google/gemini-3.1-flash-image-preview",      },    },  },}

Generazione di video

Il plugin google incluso registra anche la generazione di video tramite lo strumento condiviso video_generate.

Modello video predefinito: google/veo-3.1-fast-generate-preview
Modalità: da testo a video, da immagine a video e flussi con un singolo video di riferimento
Supporta aspectRatio (16:9, 9:16) e resolution (720P, 1080P); attualmente Veo non supporta l'output audio
Durate supportate: 4, 6 o 8 secondi (gli altri valori vengono arrotondati al valore consentito più vicino)

Per usare Google come provider video predefinito:

json5

{  agents: {    defaults: {      videoGenerationModel: {        primary: "google/veo-3.1-fast-generate-preview",      },    },  },}

Generazione musicale

Il plugin google incluso registra anche la generazione musicale tramite lo strumento condiviso music_generate.

Modello musicale predefinito: google/lyria-3-clip-preview
Supporta anche google/lyria-3-pro-preview
Controlli del prompt: lyrics e instrumental
Formato di output: mp3 per impostazione predefinita, oltre a wav su google/lyria-3-pro-preview
Input di riferimento: fino a 10 immagini
Le esecuzioni basate su sessione vengono scollegate tramite il flusso condiviso di attività/stato, incluso action: "status"

Per usare Google come provider musicale predefinito:

json5

{  agents: {    defaults: {      musicGenerationModel: {        primary: "google/lyria-3-clip-preview",      },    },  },}

Sintesi vocale

Il provider vocale google incluso usa il percorso TTS dell'API Gemini con gemini-3.1-flash-tts-preview.

Voce predefinita: Kore
Autenticazione: messages.tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY o GOOGLE_API_KEY
Output: WAV per i normali allegati TTS, Opus per le destinazioni di note vocali, PCM per conversazioni/telefonia
Output delle note vocali: il PCM di Google viene incapsulato come WAV e transcodificato in Opus a 48 kHz con ffmpeg

Il percorso TTS Gemini in batch di Google restituisce l'audio generato nella risposta generateContent completata. Per conversazioni vocali con la latenza più bassa, usa il provider vocale Google in tempo reale basato sull'API Gemini Live anziché il TTS in batch.

Per usare Google come provider TTS predefinito:

json5

{  messages: {    tts: {      auto: "always",      provider: "google",      providers: {        google: {          model: "gemini-3.1-flash-tts-preview",          speakerVoice: "Kore",          audioProfile: "Speak professionally with a calm tone.",        },      },    },  },}

Il TTS dell'API Gemini usa prompt in linguaggio naturale per controllare lo stile. Imposta audioProfile per anteporre al testo pronunciato un prompt di stile riutilizzabile. Imposta speakerName quando il testo del prompt fa riferimento a un interlocutore specifico.

Il TTS dell'API Gemini accetta anche tag audio espressivi tra parentesi quadre nel testo, come [whispers] o [laughs]. Per escludere i tag dalla risposta visibile della chat pur inviandoli al TTS, inseriscili in un blocco [[tts:text]]...[[/tts:text]]:

text

Here is the clean reply text. [[tts:text]][whispers] Here is the spoken version.[[/tts:text]]

Voce in tempo reale

Il plugin google incluso registra un provider vocale in tempo reale basato sull'API Gemini Live per bridge audio backend come Voice Call e Google Meet.

Impostazione	Percorso di configurazione	Valore predefinito
Modello	`plugins.entries.voice-call.config.realtime.providers.google.model`	`gemini-3.1-flash-live-preview`
Voce	`...google.voice`	`Kore`
Temperatura	`...google.temperature`	(non impostato)
Sensibilità iniziale VAD	`...google.startSensitivity`	(non impostato)
Sensibilità finale VAD	`...google.endSensitivity`	(non impostato)
Durata del silenzio	`...google.silenceDurationMs`	(non impostato)
Gestione dell'attività	`...google.activityHandling`	Valore predefinito di Google, `start-of-activity-interrupts`
Copertura del turno	`...google.turnCoverage`	Valore predefinito di Google, `audio-activity-and-all-video`
Disabilita VAD automatico	`...google.automaticActivityDetectionDisabled`	`false`
Ripresa della sessione	`...google.sessionResumption`	`true`
Compressione del contesto	`...google.contextWindowCompression`	`true`
Chiave API	`...google.apiKey`	Usa in alternativa `models.providers.google.apiKey`, `GEMINI_API_KEY` o `GOOGLE_API_KEY`

Esempio di configurazione in tempo reale per Voice Call:

json5

{  plugins: {    entries: {      "voice-call": {        enabled: true,        config: {          realtime: {            enabled: true,            provider: "google",            providers: {              google: {                model: "gemini-3.1-flash-live-preview",                speakerVoice: "Kore",                activityHandling: "start-of-activity-interrupts",                turnCoverage: "audio-activity-and-all-video",              },            },          },        },      },    },  },}

Per la verifica live da parte dei manutentori, esegui OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. Lo smoke test copre anche i percorsi backend/WebRTC di OpenAI; il passaggio Google genera lo stesso formato di token vincolato della Live API usato da Talk dell'interfaccia di controllo, apre l'endpoint WebSocket del browser, invia il payload di configurazione iniziale e attende setupComplete.

Configurazione avanzata

Riutilizzo diretto della cache di Gemini

Per le esecuzioni dirette dell'API Gemini (api: "google-generative-ai"), OpenClaw passa alle richieste Gemini un handle cachedContent configurato.

Configura i parametri per modello o globali con cachedContent oppure con il precedente cached_content
I parametri di un ambito più specifico (livello del modello rispetto a quello globale) hanno sempre la precedenza. Nello stesso ambito, se entrambe le chiavi sono impostate, prevale cached_content. Usa una sola chiave per ambito per evitare risultati imprevisti.
Valore di esempio: cachedContents/prebuilt-context
L'utilizzo della cache di Gemini in caso di corrispondenza viene normalizzato nel campo cacheRead di OpenClaw a partire da cachedContentTokenCount del sistema a monte

json5

{  agents: {    defaults: {      models: {        "google/gemini-2.5-pro": {          params: {            cachedContent: "cachedContents/prebuilt-context",          },        },      },    },  },}

Note sull'utilizzo della CLI di Gemini

Quando si usa il provider OAuth google-gemini-cli, OpenClaw utilizza per impostazione predefinita l'output stream-json della CLI di Gemini e normalizza l'utilizzo dal payload finale stats. Le sostituzioni precedenti con --output-format json continuano a usare il parser JSON.

Il testo della risposta trasmessa in streaming proviene dagli eventi message dell'assistente.
Per l'output JSON precedente, il testo della risposta proviene dal campo response del JSON della CLI.
Se la CLI lascia vuoto usage, l'utilizzo viene ricavato in alternativa da stats.
stats.cached viene normalizzato nel campo cacheRead di OpenClaw.
Se stats.input non è presente, OpenClaw ricava i token di input da stats.input_tokens - stats.cached.

Configurazione dell'ambiente e del daemon

Se il Gateway viene eseguito come daemon (launchd/systemd), assicurati che GEMINI_API_KEY sia disponibile per tale processo (ad esempio in ~/.openclaw/.env oppure tramite env.shellEnv).

Contenuti correlati

Selezione del modello

Scelta dei provider, dei riferimenti ai modelli e del comportamento di failover.

Generazione di immagini

Parametri condivisi dello strumento per le immagini e selezione del provider.

Generazione di video

Parametri condivisi dello strumento per i video e selezione del provider.

Generazione di musica

Parametri condivisi dello strumento per la musica e selezione del provider.

Was this useful?

Google (Gemini)

Per iniziare

Chiave API

Esegui la configurazione iniziale

Imposta un modello predefinito

Verifica che il modello sia disponibile

CLI Gemini (OAuth)

Installa la CLI Gemini

Accedi tramite OAuth

Verifica che il modello sia disponibile

Funzionalità

Ricerca web

Generazione di immagini

Generazione di video

Generazione musicale

Sintesi vocale

Voce in tempo reale

Configurazione avanzata

Contenuti correlati

On this page

Molty