Google (Gemini)

Il plugin Google fornisce accesso ai modelli Gemini tramite Google AI Studio, oltre a generazione di immagini, comprensione dei media (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: provider/modello agentRuntime.id: "google-gemini-cli" riutilizza l'OAuth della Gemini CLI mantenendo i riferimenti ai modelli canonici come google/*.

Per iniziare

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

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

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

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

openclaw models list --provider google

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

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

openclaw models list --provider google

Funzionalità

Ricerca web

Il provider di ricerca web gemini incluso usa il grounding di Google Search di Gemini. Configura una chiave di ricerca dedicata in plugins.entries.google.config.webSearch, oppure lascia che riutilizzi models.providers.google.apiKey dopo GEMINI_API_KEY:

{  plugins: {    entries: {      google: {        config: {          webSearch: {            apiKey: "AIza...", // optional if GEMINI_API_KEY or models.providers.google.apiKey is set            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // falls back to models.providers.google.baseUrl            model: "gemini-2.5-flash",          },        },      },    },  },}

La precedenza delle credenziali è webSearch.apiKey dedicata, poi GEMINI_API_KEY, poi models.providers.google.apiKey. webSearch.baseUrl è facoltativo ed esiste per proxy operatore o endpoint API Gemini compatibili; quando viene omesso, la ricerca web Gemini riutilizza models.providers.google.baseUrl. Vedi Ricerca Gemini per il comportamento dello strumento specifico del provider.

Generazione di immagini

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

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

Per usare Google come provider di immagini predefinito:

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

Generazione video

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

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

Per usare Google come provider video predefinito:

{  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, più wav su google/lyria-3-pro-preview
• Input di riferimento: fino a 10 immagini
• Le esecuzioni supportate da sessione si distaccano tramite il flusso condiviso attività/stato, incluso action: "status"

Per usare Google come provider musicale predefinito:

{  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 allegati TTS regolari, Opus per destinazioni di note vocali, PCM per Talk/telefonia
• Output nota vocale: il PCM Google viene incapsulato come WAV e transcodificato in Opus a 48 kHz con ffmpeg

Il percorso batch Gemini TTS di Google restituisce l'audio generato nella risposta generateContent completata. Per conversazioni parlate a latenza minima, usa il provider vocale in tempo reale Google basato sulla Gemini Live API invece del TTS batch.

Per usare Google come provider TTS predefinito:

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

Gemini API TTS usa prompt in linguaggio naturale per il controllo dello stile. Imposta audioProfile per anteporre un prompt di stile riutilizzabile prima del testo parlato. Imposta speakerName quando il testo del prompt fa riferimento a un parlante nominato.

Gemini API TTS accetta anche tag audio espressivi tra parentesi quadre nel testo, come [whispers] o [laughs]. Per tenere i tag fuori dalla risposta chat visibile mentre li invii al TTS, inseriscili in un blocco [[tts:text]]...[[/tts: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 sulla Gemini Live API per bridge audio backend come Voice Call e Google Meet.

Esempio di configurazione Voice Call in tempo reale:

{  plugins: {    entries: {      "voice-call": {        enabled: true,        config: {          realtime: {            enabled: true,            provider: "google",            providers: {              google: {                model: "gemini-2.5-flash-native-audio-preview-12-2025",                voice: "Kore",                activityHandling: "start-of-activity-interrupts",                turnCoverage: "only-activity",              },            },          },        },      },    },  },}

Per la verifica live dei maintainer, esegui OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. Lo smoke copre anche i percorsi backend/WebRTC di OpenAI; la parte Google emette la stessa forma di token Live API vincolato usata da Control UI Talk, apre l'endpoint WebSocket del browser, invia il payload di configurazione iniziale e attende setupComplete.

Configurazione avanzata

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

Correlati