Google (Gemini)

O Plugin do Google fornece acesso aos modelos Gemini por meio do Google AI Studio, além de geração de imagens, entendimento 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: agents.defaults.agentRuntime.id: "google-gemini-cli" reutiliza o OAuth da Gemini CLI enquanto mantém 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

# 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

# Capacidades

# Pesquisa na web

O provedor de pesquisa na web gemini integrado usa grounding da Pesquisa Google do Gemini. Configure uma chave de pesquisa dedicada em plugins.entries.google.config.webSearch, ou deixe que ele reutilize models.providers.google.apiKey depois de 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 dedicada, depois GEMINI_API_KEY, depois models.providers.google.apiKey. webSearch.baseUrl é opcional e existe para proxies de operador ou endpoints compatíveis da Gemini API; quando omitida, a pesquisa na web do Gemini reutiliza models.providers.google.baseUrl. Veja Pesquisa Gemini para o comportamento da ferramenta específico do provedor.

# Geração de imagens

O provedor de geração de imagens google integrado 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 o Google como provedor padrão de imagens:

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

# Geração de vídeo

O Plugin google integrado 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, resolution e audio
• Limite atual de duração: 4 a 8 segundos

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

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

# Geração de música

O Plugin google integrado 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, mais wav em google/lyria-3-pro-preview
• Entradas de referência: até 10 imagens
• Execuções baseadas em sessão são desanexadas por meio do 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",
      },
    },
  },
}

# Conversão de texto em fala

O provedor de fala google integrado 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 TTS Gemini em lote do Google retorna á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 baseado na Gemini Live API em vez de 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",
          voiceName: "Kore",
          audioProfile: "Speak professionally with a calm tone.",
        },
      },
    },
  },
}

O TTS da Gemini API 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 prompt se referir a um locutor nomeado.

O TTS da Gemini API também aceita tags expressivas de áudio entre colchetes no texto, como [whispers] ou [laughs]. Para manter as tags fora da resposta de chat visível 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 integrado 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.

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. 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

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

# Relacionado