Google (Gemini)

O Plugin Google fornece acesso aos modelos Gemini por meio do Google AI Studio, além de geração de imagens, compreensão de mídia (imagem/áudio/vídeo), conversão de texto em fala e pesquisa na web via Gemini Grounding.

• Provedor: google
• Autenticação: GEMINI_API_KEY ou GOOGLE_API_KEY
• API: Google Gemini API
• Opção de runtime: provedor/modelo agentRuntime.id: "google-gemini-cli" reutiliza o OAuth do Gemini CLI, mantendo as refs de modelo canônicas como google/*.

Primeiros passos

Escolha seu método de autenticação preferido e siga as etapas de configuração.

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

Capacidades

Pesquisa na web

O provedor de pesquisa na web gemini incluído usa grounding do Google Search no Gemini. Configure uma chave de pesquisa dedicada em plugins.entries.google.config.webSearch, ou permita que ele reutilize models.providers.google.apiKey após 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",          },        },      },    },  },}

A precedência de credenciais é webSearch.apiKey dedicado, depois GEMINI_API_KEY, depois models.providers.google.apiKey. webSearch.baseUrl é opcional e existe para proxies de operadores ou endpoints compatíveis da Gemini API; quando omitido, a pesquisa na web do Gemini reutiliza models.providers.google.baseUrl. Consulte Pesquisa Gemini para o comportamento da ferramenta específico do provedor.

Geração de imagens

O provedor de geração de imagens google incluído usa como padrão google/gemini-3.1-flash-image-preview.

• Também oferece suporte a google/gemini-3-pro-image-preview
• Gerar: até 4 imagens por solicitação
• Modo de edição: habilitado, até 5 imagens de entrada
• Controles de geometria: size, aspectRatio e resolution

Para usar Google como provedor de imagens padrão:

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

Geração de vídeo

O Plugin google incluído também registra geração de vídeo por meio da ferramenta compartilhada video_generate.

• Modelo de vídeo padrão: google/veo-3.1-fast-generate-preview
• Modos: fluxos de texto para vídeo, imagem para vídeo e referência de vídeo único
• Oferece suporte a aspectRatio (16:9, 9:16) e resolution (720P, 1080P); saída de áudio não é compatível com Veo atualmente
• Durações compatíveis: 4, 6 ou 8 segundos (outros valores se ajustam ao valor permitido mais próximo)

Para usar Google como provedor de vídeo padrão:

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

Geração de música

O Plugin google incluído também registra geração de música por meio da ferramenta compartilhada music_generate.

• Modelo de música padrão: google/lyria-3-clip-preview
• Também oferece suporte a google/lyria-3-pro-preview
• Controles de prompt: lyrics e instrumental
• Formato de saída: mp3 por padrão, além de wav em google/lyria-3-pro-preview
• Entradas de referência: até 10 imagens
• Execuções com sessão destacam-se por meio do fluxo compartilhado de tarefa/status, incluindo action: "status"

Para usar Google como provedor de música padrão:

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

Conversão de texto em fala

O provedor de fala google incluído usa o caminho de TTS da Gemini API com gemini-3.1-flash-tts-preview.

• Voz padrão: Kore
• Autenticação: messages.tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY ou GOOGLE_API_KEY
• Saída: WAV para anexos TTS comuns, Opus para destinos de nota de voz, PCM para Talk/telefonia
• Saída de nota de voz: o PCM do Google é encapsulado como WAV e transcodificado para Opus de 48 kHz com ffmpeg

O caminho de TTS Gemini em lote do Google retorna o áudio gerado na resposta generateContent concluída. Para conversas faladas com a menor latência, use o provedor de voz em tempo real do Google apoiado pela Gemini Live API em vez de TTS em lote.

Para usar Google como provedor de TTS padrão:

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

O TTS da Gemini API usa prompting em linguagem natural para controle de estilo. Defina audioProfile para prefixar um prompt de estilo reutilizável antes do texto falado. Defina speakerName quando o texto do prompt fizer referência a um falante nomeado.

O TTS da Gemini API também aceita tags de áudio expressivas entre colchetes no texto, como [whispers] ou [laughs]. Para manter tags fora da resposta visível do chat enquanto as envia ao TTS, coloque-as dentro de um bloco [[tts:text]]...[[/tts:text]]:

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

Voz em tempo real

O Plugin google incluído registra um provedor de voz em tempo real apoiado pela Gemini Live API para pontes de áudio de backend, como Voice Call e Google Meet.

Exemplo de configuração em tempo real do 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",              },            },          },        },      },    },  },}

Para verificação ao vivo por mantenedores, execute OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. O smoke também cobre caminhos de backend/WebRTC da OpenAI; a etapa do Google emite o mesmo formato de token restrito da Live API usado pelo Control UI Talk, abre o endpoint WebSocket do navegador, envia o payload inicial de configuração e aguarda setupComplete.

Configuração avançada

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

Relacionado