Google (Gemini)

Il Plugin Google fornisce accesso ai modelli Gemini tramite Google AI Studio, oltre a generazione di immagini, comprensione dei media (immagine/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 runtime: agents.defaults.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

# Homebrew
brew install gemini-cli

# or npm
npm 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 degli operatori o endpoint Gemini API compatibili; quando 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 di input
• Controlli di geometria: 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 da testo a video, da immagine a video e con riferimento a un singolo video
• Supporta aspectRatio, resolution e audio
• Limite attuale della durata: da 4 a 8 secondi

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 basate su sessione si sganciano tramite il flusso condiviso di 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 della Gemini API 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 gli allegati TTS regolari, Opus per destinazioni con note vocali, PCM per Talk/telefonia
• Output note vocali: il PCM Google viene incapsulato come WAV e transcodificato in Opus a 48 kHz con ffmpeg

Il percorso Gemini TTS batch di Google restituisce l'audio generato nella risposta generateContent completata. Per conversazioni vocali con la latenza più bassa, usa il provider di voce 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 mantenere i tag fuori dalla risposta chat visibile mentre li invii al TTS, inseriscili dentro 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 di voce in tempo reale basato sulla Gemini Live API per bridge audio backend come Voice Call e Google Meet.

Esempio di configurazione in tempo reale per Voice Call:

{
  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. Il ramo Google genera lo stesso formato di token Live API vincolato usato da Control UI Talk, apre l'endpoint WebSocket del browser, invia il payload iniziale di configurazione e attende setupComplete.

# Configurazione avanzata

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

# Correlati