Providers

Google (Gemini)

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: agentRuntime.id: "google-gemini-cli" reutiliza o OAuth da Gemini CLI, mantendo 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.

Chave de API

Mais indicado para: acesso padrão à API Gemini por meio do Google AI Studio.

Execute a configuração inicial

bash

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

Ou forneça a chave diretamente:

bash

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

Defina um modelo padrão

json5

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

Verifique se o modelo está disponível

bash

openclaw models list --provider google

Gemini CLI (OAuth)

Mais indicado para: reutilizar um login existente da Gemini CLI via OAuth com PKCE em vez de usar uma chave de API separada.

Instale a Gemini CLI

O comando local gemini deve estar disponível no PATH.

bash

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

O OpenClaw oferece suporte tanto a instalações pelo Homebrew quanto a instalações globais pelo npm, incluindo layouts comuns do Windows/npm.

Entre via OAuth

bash

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

Verifique se o modelo está disponível

bash

openclaw models list --provider google

Modelo padrão: google/gemini-3.1-pro-preview
Runtime: google-gemini-cli
Alias: gemini-cli

O ID de modelo da API Gemini para o Gemini 3.1 Pro é gemini-3.1-pro-preview. O OpenClaw aceita a forma abreviada google/gemini-3.1-pro como um alias de conveniência e a normaliza antes das chamadas ao provedor.

Variáveis de ambiente:

OPENCLAW_GEMINI_OAUTH_CLIENT_ID / GEMINI_CLI_OAUTH_CLIENT_ID
OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET / GEMINI_CLI_OAUTH_CLIENT_SECRET

As referências de modelo google-gemini-cli/* são aliases de compatibilidade legados. Novas configurações devem usar referências de modelo google/* com o runtime google-gemini-cli quando quiserem executar localmente a Gemini CLI.

Recursos

Recurso	Compatível
Conclusões de chat	Sim
Geração de imagens	Sim
Geração de música	Sim
Conversão de texto em fala	Sim
Voz em tempo real	Sim (Google Live API)
Compreensão de imagens	Sim
Transcrição de áudio	Sim
Compreensão de vídeo	Sim
Pesquisa na web (Grounding)	Sim
Pensamento/raciocínio	Sim (Gemini 2.5+ / Gemini 3+)
Modelos Gemma 4	Sim

Pesquisa na web

O provedor integrado de pesquisa na web gemini usa o Grounding com a Pesquisa Google do 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:

json5

{  plugins: {    entries: {      google: {        config: {          webSearch: {            apiKey: "AIza...", // opcional se GEMINI_API_KEY ou models.providers.google.apiKey estiver definida            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // usa models.providers.google.baseUrl como alternativa            model: "gemini-2.5-flash",          },        },      },    },  },}

A ordem de precedência das credenciais é: webSearch.apiKey dedicada, depois GEMINI_API_KEY e, em seguida, models.providers.google.apiKey. webSearch.baseUrl é opcional e existe para proxies de operadores ou endpoints compatíveis com a API Gemini; quando omitida, a pesquisa na web do Gemini reutiliza models.providers.google.baseUrl. Consulte Pesquisa do Gemini para saber mais sobre o comportamento da ferramenta específico do provedor.

Tip

Os modelos Gemini 3 usam thinkingLevel em vez de thinkingBudget. O OpenClaw mapeia os controles de raciocínio do Gemini 3, Gemini 3.1 e dos aliases gemini-*-latest para thinkingLevel, para que execuções padrão/de baixa latência não enviem valores desativados de thinkingBudget.

/think adaptive preserva a semântica de pensamento dinâmico do Google em vez de selecionar um nível fixo do OpenClaw. O Gemini 3 e o Gemini 3.1 omitem um thinkingLevel fixo para que o Google possa escolher o nível; o Gemini 2.5 envia o sentinela dinâmico do Google thinkingBudget: -1.

Os modelos Gemma 4 (por exemplo, gemma-4-26b-a4b-it) oferecem suporte ao modo de pensamento. O OpenClaw reescreve thinkingBudget como um thinkingLevel compatível do Google para o Gemma 4. Definir o pensamento como off o mantém desativado, em vez de mapeá-lo para MINIMAL.

O Gemini 2.5 Pro funciona apenas no modo de pensamento e rejeita um thinkingBudget: 0 explícito; o OpenClaw remove esse valor das solicitações do Gemini 2.5 Pro em vez de enviá-lo.

Geração de imagens

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

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

Para usar o Google como provedor de imagens padrão:

json5

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

Geração de vídeos

O plugin integrado google também registra a geração de vídeos por meio da ferramenta compartilhada video_generate.

Modelo de vídeo padrão: google/veo-3.1-fast-generate-preview
Modos: texto para vídeo, imagem para vídeo e fluxos com referência de um único vídeo
Oferece suporte a aspectRatio (16:9, 9:16) e resolution (720P, 1080P); atualmente, o Veo não oferece suporte à saída de áudio
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 de vídeos padrão:

json5

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

Geração de música

O plugin integrado google também registra a 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 do 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 suporte de sessão são desvinculadas por meio do fluxo compartilhado de tarefa/status, incluindo action: "status"

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

json5

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

Conversão de texto em fala

O provedor de fala integrado google 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 comuns de TTS, Opus para destinos de mensagem de voz e PCM para Talk/telefonia
Saída de mensagem de voz: o PCM do Google é encapsulado como WAV e transcodificado para Opus de 48 kHz com ffmpeg

O caminho de TTS em lote do Gemini do Google retorna o áudio gerado na resposta concluída de generateContent. Para conversas faladas com a menor latência possível, 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 de TTS padrão:

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.",        },      },    },  },}

O TTS da API Gemini usa prompts em linguagem natural para controlar o estilo. Defina audioProfile para acrescentar um prompt de estilo reutilizável antes do texto falado. Defina speakerName quando o texto do prompt se referir a um locutor pelo nome.

O TTS da API Gemini também aceita tags expressivas de áudio entre colchetes no texto, como [whispers] ou [laughs]. Para evitar que as tags apareçam na resposta visível do chat e ainda enviá-las ao TTS, coloque-as dentro de um bloco [[tts:text]]...[[/tts:text]]:

text

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

Voz em tempo real

O plugin integrado google 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ção	Caminho de configuração	Padrão
Modelo	`plugins.entries.voice-call.config.realtime.providers.google.model`	`gemini-3.1-flash-live-preview`
Voz	`...google.voice`	`Kore`
Temperatura	`...google.temperature`	(não definido)
Sensibilidade inicial do VAD	`...google.startSensitivity`	(não definido)
Sensibilidade final do VAD	`...google.endSensitivity`	(não definido)
Duração do silêncio	`...google.silenceDurationMs`	(não definido)
Tratamento de atividade	`...google.activityHandling`	Padrão do Google, `start-of-activity-interrupts`
Cobertura do turno	`...google.turnCoverage`	Padrão do Google, `audio-activity-and-all-video`
Desativar VAD automático	`...google.automaticActivityDetectionDisabled`	`false`
Retomada de sessão	`...google.sessionResumption`	`true`
Compactação de contexto	`...google.contextWindowCompression`	`true`
Chave de API	`...google.apiKey`	Usa como alternativas `models.providers.google.apiKey`, `GEMINI_API_KEY` ou `GOOGLE_API_KEY`

Exemplo de configuração em tempo real de chamada de voz:

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",              },            },          },        },      },    },  },}

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

Configuração avançada

Reutilização direta do cache do Gemini

Para execuções diretas da API Gemini (api: "google-generative-ai"), o OpenClaw repassa um identificador cachedContent configurado às solicitações do Gemini.

Configure parâmetros por modelo ou globais com cachedContent ou o formato legado cached_content
Os parâmetros de um escopo mais específico (nível do modelo em vez do global) sempre prevalecem. No mesmo escopo, se ambas as chaves estiverem definidas, cached_content prevalece. Use apenas uma chave por escopo para evitar surpresas.
Exemplo de valor: cachedContents/prebuilt-context
O uso de acertos no cache do Gemini é normalizado no cacheRead do OpenClaw a partir de cachedContentTokenCount do serviço de origem

json5

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

Observações sobre o uso da CLI do Gemini

Ao usar o provedor OAuth google-gemini-cli, o OpenClaw usa por padrão a saída stream-json da CLI do Gemini e normaliza o uso a partir da carga útil stats final. Substituições legadas com --output-format json ainda usam o analisador JSON.

O texto da resposta transmitida vem dos eventos message do assistente.
Para a 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 calcula os tokens de entrada a partir de stats.input_tokens - stats.cached.

Configuração do ambiente e do daemon

Se o Gateway for executado como daemon (launchd/systemd), certifique-se de que GEMINI_API_KEY esteja disponível para esse processo (por exemplo, em ~/.openclaw/.env ou por meio de env.shellEnv).

Relacionados

Seleção de modelos

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

Geração de imagens

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

Geração de vídeos

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

Geração de músicas

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

Was this useful?

Google (Gemini)

Primeiros passos

Chave de API

Execute a configuração inicial

Defina um modelo padrão

Verifique se o modelo está disponível

Gemini CLI (OAuth)

Instale a Gemini CLI

Entre via OAuth

Verifique se o modelo está disponível

Recursos

Pesquisa na web

Geração de imagens

Geração de vídeos

Geração de música

Conversão de texto em fala

Voz em tempo real

Configuração avançada

Relacionados

On this page

Molty