Pular para o conteúdo principal
O Plugin do 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: API Google Gemini
  • Opção de runtime: provedor/modelo agentRuntime.id: "google-gemini-cli" reutiliza o OAuth do Gemini CLI enquanto mantém as referências de modelo canônicas como google/*.

​
Primeiros passos

Escolha seu método de autenticação preferido e siga as etapas de configuração.
Melhor para: acesso padrão à API Gemini por meio do Google AI Studio.
1

Run onboarding

openclaw onboard --auth-choice gemini-api-key
Ou passe a chave diretamente:
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY"
2

Set a default model

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

Verify the model is available

openclaw models list --provider google
As variáveis de ambiente GEMINI_API_KEY e GOOGLE_API_KEY são aceitas. Use a que você já tiver configurada.

​
Capacidades

CapacidadeCompatível
Conclusões de chatSim
Geração de imagensSim
Geração de músicaSim
Conversão de texto em falaSim
Voz em tempo realSim (Google Live API)
Compreensão de imagensSim
Transcrição de áudioSim
Compreensão de vídeoSim
Pesquisa na web (Grounding)Sim
Thinking/raciocínioSim (Gemini 2.5+ / Gemini 3+)
Modelos Gemma 4Sim

​
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 ela 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 das credenciais é webSearch.apiKey dedicada, depois GEMINI_API_KEY, depois models.providers.google.apiKey. webSearch.baseUrl é opcional e existe para proxies de operadores ou endpoints compatíveis da API Gemini; quando omitida, a pesquisa na web do Gemini reutiliza models.providers.google.baseUrl. Consulte Pesquisa Gemini para o comportamento da ferramenta específico do provedor.
Modelos Gemini 3 usam thinkingLevel em vez de thinkingBudget. O OpenClaw mapeia controles de raciocínio de aliases Gemini 3, Gemini 3.1 e gemini-*-latest para thinkingLevel, para que execuções padrão/de baixa latência não enviem valores thinkingBudget desabilitados./think adaptive mantém a semântica de pensamento dinâmico do Google em vez de escolher um nível fixo do OpenClaw. Gemini 3 e Gemini 3.1 omitem um thinkingLevel fixo para que o Google possa escolher o nível; Gemini 2.5 envia o sentinela dinâmico do Google thinkingBudget: -1.Modelos Gemma 4 (por exemplo, gemma-4-26b-a4b-it) oferecem suporte ao modo de pensamento. O OpenClaw reescreve thinkingBudget para um thinkingLevel compatível do Google para Gemma 4. Definir o pensamento como off preserva o pensamento desabilitado em vez de mapear para MINIMAL.

​
Geração de imagens

O provedor de geração de imagens google incluído usa por 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 o Google como provedor padrão de imagens: 
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "google/gemini-3.1-flash-image-preview",
      },
    },
  },
}
Consulte Geração de Imagens para parâmetros compartilhados da ferramenta, seleção de provedor e comportamento de failover.

​
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 o Veo atualmente
  • Durações compatíveis: 4, 6 ou 8 segundos (outros valores são ajustados para o valor permitido mais próximo)
Para usar o Google como provedor padrão de vídeo: 
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
      },
    },
  },
}
Consulte Geração de Vídeo para parâmetros compartilhados da ferramenta, seleção de provedor e comportamento de failover.

​
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 se desvinculam pelo fluxo compartilhado de tarefa/status, incluindo action: "status"
Para usar o Google como provedor padrão de música: 
{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
      },
    },
  },
}
Consulte Geração de Música para parâmetros compartilhados da ferramenta, seleção de provedor e comportamento de failover.

​
Conversão de texto em fala

O provedor de fala google incluído usa o caminho de TTS da API Gemini 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 regulares, Opus para destinos de notas 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 TTS em lote do Gemini do Google retorna o áudio gerado na resposta generateContent concluída. Para conversas faladas de menor latência, use o provedor de voz em tempo real do Google baseado na Gemini Live API em vez do TTS em lote. Para usar o Google como provedor TTS padrão: 
{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          model: "gemini-3.1-flash-tts-preview",
          speakerVoice: "Kore",
          audioProfile: "Speak professionally with a calm tone.",
        },
      },
    },
  },
}
O TTS da API Gemini usa prompts 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 seu prompt se referir a um falante nomeado. O TTS da API Gemini também aceita tags expressivas de áudio entre colchetes no texto, como [whispers] ou [laughs]. Para manter as 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]]
Uma chave de API do Google Cloud Console restrita à API Gemini é válida para este provedor. Este não é o caminho separado da API Cloud Text-to-Speech.

​
Voz em tempo real

O Plugin google incluído registra um provedor de voz em tempo real baseado na Gemini Live API para pontes de áudio de backend, como Voice Call e Google Meet.
ConfiguraçãoCaminho de configuraçãoPadrão
Modeloplugins.entries.voice-call.config.realtime.providers.google.modelgemini-2.5-flash-native-audio-preview-12-2025
Voz...google.voiceKore
Temperatura...google.temperature(não definido)
Sensibilidade inicial de VAD...google.startSensitivity(não definido)
Sensibilidade final de VAD...google.endSensitivity(não definido)
Duração do silêncio...google.silenceDurationMs(não definido)
Tratamento de atividade...google.activityHandlingPadrão do Google, start-of-activity-interrupts
Cobertura de turno...google.turnCoveragePadrão do Google, only-activity
Desativar VAD automático...google.automaticActivityDetectionDisabledfalse
Retomada de sessão...google.sessionResumptiontrue
Compressão de contexto...google.contextWindowCompressiontrue
Chave de API...google.apiKeyRecorre a models.providers.google.apiKey, GEMINI_API_KEY ou GOOGLE_API_KEY
Exemplo de configuração em tempo real de 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",
                speakerVoice: "Kore",
                activityHandling: "start-of-activity-interrupts",
                turnCoverage: "only-activity",
              },
            },
          },
        },
      },
    },
  },
}
A Google Live API usa áudio bidirecional e chamada de função por um WebSocket. O OpenClaw adapta o áudio da ponte de telefonia/Meet para o fluxo PCM da Live API do Gemini e mantém as chamadas de ferramentas no contrato de voz em tempo real compartilhado. Deixe temperature sem definição, a menos que você precise alterar a amostragem; o OpenClaw omite valores não positivos porque o Google Live pode retornar transcrições sem áudio para temperature: 0. A transcrição da Gemini API é ativada sem languageCodes; o SDK atual do Google rejeita dicas de código de idioma nesse caminho de API.
O Control UI Talk oferece suporte a sessões do Google Live no navegador com tokens restritos de uso único. Provedores de voz em tempo real apenas de backend também podem ser executados pelo transporte genérico de relay do Gateway, que mantém as credenciais do provedor no Gateway.
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 a carga inicial de configuração e aguarda setupComplete.

​
Configuração avançada

Para execuções diretas da Gemini API (api: "google-generative-ai"), o OpenClaw repassa um identificador cachedContent configurado para as solicitações ao Gemini.
  • Configure parâmetros por modelo ou globais com cachedContent ou o legado cached_content
  • Se ambos estiverem presentes, cachedContent prevalece
  • Valor de exemplo: cachedContents/prebuilt-context
  • O uso de acertos de cache do Gemini é normalizado no cacheRead do OpenClaw a partir de cachedContentTokenCount upstream
{
  agents: {
    defaults: {
      models: {
        "google/gemini-2.5-pro": {
          params: {
            cachedContent: "cachedContents/prebuilt-context",
          },
        },
      },
    },
  },
}
Ao usar o provedor OAuth google-gemini-cli, o OpenClaw usa a saída stream-json da Gemini CLI por padrão e normaliza o uso a partir da carga final stats. Substituições legadas de --output-format json ainda usam o analisador JSON.
  • O texto da resposta transmitida vem de eventos message do assistente.
  • Para saída JSON legada, o texto da resposta vem do campo response do JSON da CLI.
  • O uso recorre a stats quando a CLI deixa usage vazio.
  • stats.cached é normalizado no cacheRead do OpenClaw.
  • Se stats.input estiver ausente, o OpenClaw deriva os tokens de entrada de stats.input_tokens - stats.cached.
Se o Gateway for executado como um daemon (launchd/systemd), garanta que GEMINI_API_KEY esteja disponível para esse processo (por exemplo, em ~/.openclaw/.env ou via env.shellEnv).

​
Relacionado

Model selection

Escolha de provedores, referências de modelo e comportamento de failover.

Image generation

Parâmetros compartilhados da ferramenta de imagem e seleção de provedor.

Video generation

Parâmetros compartilhados da ferramenta de vídeo e seleção de provedor.

Music generation

Parâmetros compartilhados da ferramenta de música e seleção de provedor.