Saltar al contenido principal
El plugin de Google proporciona acceso a los modelos Gemini a través de Google AI Studio, además de generación de imágenes, comprensión de medios (imagen/audio/video), texto a voz y búsqueda web mediante Gemini Grounding.
  • Proveedor: google
  • Autenticación: GEMINI_API_KEY o GOOGLE_API_KEY
  • API: API de Google Gemini
  • Opción de runtime: agentRuntime.id: "google-gemini-cli" reutiliza OAuth de Gemini CLI mientras mantiene las referencias de modelo canónicas como google/*.

​
Primeros pasos

Elige tu método de autenticación preferido y sigue los pasos de configuración.
Recomendado para: acceso estándar a la API de Gemini mediante Google AI Studio.
1

Ejecutar la incorporación

openclaw onboard --auth-choice gemini-api-key
O pasa la clave directamente:
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY"
2

Establecer un modelo predeterminado

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

Verificar que el modelo esté disponible

openclaw models list --provider google
Se aceptan tanto GEMINI_API_KEY como GOOGLE_API_KEY. Usa la que ya tengas configurada.
google/gemini-3-pro-preview se retiró el 2026-03-09; usa google/gemini-3.1-pro-preview en su lugar. Volver a ejecutar la configuración de la clave de API de Gemini (openclaw onboard --auth-choice gemini-api-key o openclaw models auth login --provider google) reescribe un valor predeterminado configurado obsoleto al modelo actual.

​
Capacidades

CapacidadCompatible
Completados de chatSí
Generación de imágenesSí
Generación de músicaSí
Texto a vozSí
Voz en tiempo realSí (Google Live API)
Comprensión de imágenesSí
Transcripción de audioSí
Comprensión de videoSí
Búsqueda web (Grounding)Sí
Pensamiento/razonamientoSí (Gemini 2.5+ / Gemini 3+)
Modelos Gemma 4Sí

​
Búsqueda web

El proveedor de búsqueda web gemini incluido usa grounding de Google Search de Gemini. Configura una clave de búsqueda dedicada en plugins.entries.google.config.webSearch, o deja que reutilice models.providers.google.apiKey después 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",
          },
        },
      },
    },
  },
}
La precedencia de credenciales es webSearch.apiKey dedicada, luego GEMINI_API_KEY, luego models.providers.google.apiKey. webSearch.baseUrl es opcional y existe para proxies de operador o endpoints compatibles de Gemini API; cuando se omite, la búsqueda web de Gemini reutiliza models.providers.google.baseUrl. Consulta Búsqueda de Gemini para ver el comportamiento de herramienta específico del proveedor.
Los modelos Gemini 3 usan thinkingLevel en lugar de thinkingBudget. OpenClaw mapea los controles de razonamiento de Gemini 3, Gemini 3.1 y alias gemini-*-latest a thinkingLevel para que las ejecuciones predeterminadas/de baja latencia no envíen valores thinkingBudget deshabilitados./think adaptive conserva la semántica de pensamiento dinámico de Google en lugar de elegir un nivel fijo de OpenClaw. Gemini 3 y Gemini 3.1 omiten un thinkingLevel fijo para que Google pueda elegir el nivel; Gemini 2.5 envía el centinela dinámico de Google thinkingBudget: -1.Los modelos Gemma 4 (por ejemplo gemma-4-26b-a4b-it) admiten modo de pensamiento. OpenClaw reescribe thinkingBudget a un thinkingLevel de Google compatible para Gemma 4. Establecer el pensamiento en off conserva el pensamiento deshabilitado en lugar de mapearlo a MINIMAL.Gemini 2.5 Pro solo funciona en modo de pensamiento y rechaza un thinkingBudget: 0 explícito; OpenClaw elimina ese valor para las solicitudes de Gemini 2.5 Pro en lugar de enviarlo.

​
Generación de imágenes

El proveedor de generación de imágenes google incluido usa de forma predeterminada google/gemini-3.1-flash-image-preview.
  • También admite google/gemini-3-pro-image-preview
  • Generar: hasta 4 imágenes por solicitud
  • Modo de edición: habilitado, hasta 5 imágenes de entrada
  • Controles de geometría: size, aspectRatio y resolution
Para usar Google como proveedor de imágenes predeterminado: 
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "google/gemini-3.1-flash-image-preview",
      },
    },
  },
}
Consulta Generación de imágenes para ver parámetros compartidos de la herramienta, selección de proveedor y comportamiento de conmutación por error.

​
Generación de video

El plugin google incluido también registra generación de video mediante la herramienta compartida video_generate.
  • Modelo de video predeterminado: google/veo-3.1-fast-generate-preview
  • Modos: flujos de texto a video, imagen a video y referencia de video único
  • Admite aspectRatio (16:9, 9:16) y resolution (720P, 1080P); la salida de audio no es compatible con Veo hoy
  • Duraciones admitidas: 4, 6 u 8 segundos (otros valores se ajustan al valor permitido más cercano)
Para usar Google como proveedor de video predeterminado: 
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
      },
    },
  },
}
Consulta Generación de video para ver parámetros compartidos de la herramienta, selección de proveedor y comportamiento de conmutación por error.

​
Generación de música

El plugin google incluido también registra generación de música mediante la herramienta compartida music_generate.
  • Modelo de música predeterminado: google/lyria-3-clip-preview
  • También admite google/lyria-3-pro-preview
  • Controles de prompt: lyrics e instrumental
  • Formato de salida: mp3 de forma predeterminada, además de wav en google/lyria-3-pro-preview
  • Entradas de referencia: hasta 10 imágenes
  • Las ejecuciones respaldadas por sesión se desacoplan mediante el flujo compartido de tarea/estado, incluido action: "status"
Para usar Google como proveedor de música predeterminado: 
{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
      },
    },
  },
}
Consulta Generación de música para ver parámetros compartidos de la herramienta, selección de proveedor y comportamiento de conmutación por error.

​
Texto a voz

El proveedor de voz google incluido usa la ruta TTS de Gemini API con gemini-3.1-flash-tts-preview.
  • Voz predeterminada: Kore
  • Autenticación: messages.tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY o GOOGLE_API_KEY
  • Salida: WAV para adjuntos TTS normales, Opus para destinos de notas de voz, PCM para Talk/telefonía
  • Salida de nota de voz: Google PCM se envuelve como WAV y se transcodifica a Opus de 48 kHz con ffmpeg
La ruta Gemini TTS por lotes de Google devuelve el audio generado en la respuesta generateContent completada. Para conversaciones habladas con la menor latencia, usa el proveedor de voz en tiempo real de Google respaldado por Gemini Live API en lugar de TTS por lotes. Para usar Google como proveedor TTS predeterminado: 
{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          model: "gemini-3.1-flash-tts-preview",
          speakerVoice: "Kore",
          audioProfile: "Speak professionally with a calm tone.",
        },
      },
    },
  },
}
Gemini API TTS usa prompting en lenguaje natural para controlar el estilo. Configura audioProfile para anteponer un prompt de estilo reutilizable antes del texto hablado. Configura speakerName cuando tu texto de prompt haga referencia a un hablante con nombre. Gemini API TTS también acepta etiquetas de audio expresivas entre corchetes en el texto, como [whispers] o [laughs]. Para mantener las etiquetas fuera de la respuesta visible del chat mientras se envían a TTS, colócalas dentro de un bloque [[tts:text]]...[[/tts:text]]: 
Here is the clean reply text.

[[tts:text]][whispers] Here is the spoken version.[[/tts:text]]
Una clave de API de Google Cloud Console restringida a la API de Gemini es válida para este proveedor. Esta no es la ruta separada de Cloud Text-to-Speech API.

​
Voz en tiempo real

El plugin google incluido registra un proveedor de voz en tiempo real respaldado por Gemini Live API para puentes de audio backend como Voice Call y Google Meet.
ConfiguraciónRuta de configuraciónValor predeterminado
Modeloplugins.entries.voice-call.config.realtime.providers.google.modelgemini-2.5-flash-native-audio-preview-12-2025
Voz...google.voiceKore
Temperatura...google.temperature(sin definir)
Sensibilidad de inicio de VAD...google.startSensitivity(sin definir)
Sensibilidad de fin de VAD...google.endSensitivity(sin definir)
Duración del silencio...google.silenceDurationMs(sin definir)
Gestión de actividad...google.activityHandlingValor predeterminado de Google, start-of-activity-interrupts
Cobertura de turno...google.turnCoverageValor predeterminado de Google, only-activity
Desactivar VAD automático...google.automaticActivityDetectionDisabledfalse
Reanudación de sesión...google.sessionResumptiontrue
Compresión de contexto...google.contextWindowCompressiontrue
Clave de API...google.apiKeyRecurre a models.providers.google.apiKey, GEMINI_API_KEY o GOOGLE_API_KEY
Ejemplo de configuración en tiempo 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",
              },
            },
          },
        },
      },
    },
  },
}
Google Live API usa audio bidireccional y llamadas a funciones mediante un WebSocket. OpenClaw adapta el audio del puente de telefonía/Meet al flujo de PCM de Live API de Gemini y mantiene las llamadas a herramientas en el contrato de voz en tiempo real compartido. Deja temperature sin definir a menos que necesites cambios de muestreo; OpenClaw omite los valores no positivos porque Google Live puede devolver transcripciones sin audio para temperature: 0. La transcripción de Gemini API se habilita sin languageCodes; el SDK actual de Google rechaza las sugerencias de código de idioma en esta ruta de API.
Control UI Talk admite sesiones de navegador de Google Live con tokens de un solo uso restringidos. Los proveedores de voz en tiempo real solo de backend también pueden ejecutarse mediante el transporte de retransmisión genérico de Gateway, que mantiene las credenciales del proveedor en el Gateway.
Para la verificación en vivo de mantenedor, ejecuta OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. La prueba smoke también cubre las rutas de backend/WebRTC de OpenAI; el tramo de Google emite la misma forma de token restringido de Live API que usa Control UI Talk, abre el endpoint WebSocket del navegador, envía la carga útil de configuración inicial y espera setupComplete.

​
Configuración avanzada

Para ejecuciones directas de Gemini API (api: "google-generative-ai"), OpenClaw pasa un identificador cachedContent configurado a las solicitudes de Gemini.
  • Configura parámetros por modelo o globales con cachedContent o el heredado cached_content
  • Los parámetros de un ámbito más específico (nivel de modelo sobre global) siempre prevalecen. Dentro del mismo ámbito, si ambas claves están definidas, cached_content prevalece. Usa solo una clave por ámbito para evitar sorpresas.
  • Valor de ejemplo: cachedContents/prebuilt-context
  • El uso de aciertos de caché de Gemini se normaliza en cacheRead de OpenClaw desde cachedContentTokenCount ascendente
{
  agents: {
    defaults: {
      models: {
        "google/gemini-2.5-pro": {
          params: {
            cachedContent: "cachedContents/prebuilt-context",
          },
        },
      },
    },
  },
}
Al usar el proveedor OAuth google-gemini-cli, OpenClaw usa la salida stream-json de Gemini CLI de forma predeterminada y normaliza el uso desde la carga útil final stats. Las anulaciones heredadas de --output-format json siguen usando el analizador JSON.
  • El texto de respuesta transmitido proviene de los eventos message del asistente.
  • Para la salida JSON heredada, el texto de respuesta proviene del campo response del JSON de la CLI.
  • El uso recurre a stats cuando la CLI deja usage vacío.
  • stats.cached se normaliza en cacheRead de OpenClaw.
  • Si falta stats.input, OpenClaw deriva los tokens de entrada de stats.input_tokens - stats.cached.
Si el Gateway se ejecuta como daemon (launchd/systemd), asegúrate de que GEMINI_API_KEY esté disponible para ese proceso (por ejemplo, en ~/.openclaw/.env o mediante env.shellEnv).

​
Relacionado

Selección de modelo

Elección de proveedores, referencias de modelo y comportamiento de conmutación por error.

Generación de imágenes

Parámetros compartidos de herramientas de imagen y selección de proveedor.

Generación de video

Parámetros compartidos de herramientas de video y selección de proveedor.

Generación de música

Parámetros compartidos de herramientas de música y selección de proveedor.