Providers

Google (Gemini)

El plugin de Google proporciona acceso a los modelos Gemini mediante Google AI Studio, además de generación de imágenes, comprensión multimedia (imagen/audio/vídeo), 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 entorno de ejecución: agentRuntime.id: "google-gemini-cli" reutiliza el OAuth de la CLI de Gemini y mantiene las referencias de modelos en su forma canónica como google/*.

Primeros pasos

Elija el método de autenticación que prefiera y siga los pasos de configuración.

Clave de API

Ideal para: acceso estándar a la API de Gemini mediante Google AI Studio.

Obtener una clave de API

Cree una clave gratuita en Google AI Studio.

Ejecutar la incorporación

bash

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

O proporcione la clave directamente:

bash

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

Establecer un modelo predeterminado

json5

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

Verificar que el modelo esté disponible

bash

openclaw models list --provider google

Con una clave de API configurada, OpenClaw actualiza el catálogo de modelos de texto de Google AI Studio desde la API models.list de Gemini. Por lo tanto, las variantes de Gemini 3 Pro, Flash y Flash-Lite recién publicadas aparecen en openclaw models list --provider google sin esperar a una nueva versión de OpenClaw. Si la detección no está disponible, OpenClaw conserva el catálogo alternativo incluido.

CLI de Gemini (OAuth)

Ideal para: iniciar sesión con una cuenta de Google mediante el OAuth de la CLI de Gemini en lugar de utilizar una clave de API independiente.

Instalar la CLI de Gemini

El comando local gemini debe estar disponible en PATH.

bash

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

OpenClaw admite tanto instalaciones mediante Homebrew como instalaciones globales mediante npm, incluidas las disposiciones habituales de Windows/npm.

Iniciar sesión mediante OAuth

bash

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

Verificar que el modelo esté disponible

bash

openclaw models list --provider google

Modelo predeterminado: google/gemini-3.1-pro-preview
Entorno de ejecución: google-gemini-cli
Alias: gemini-cli

El identificador del modelo de la API de Gemini para Gemini 3.1 Pro es gemini-3.1-pro-preview. OpenClaw acepta la forma abreviada google/gemini-3.1-pro como alias práctico y la normaliza antes de las llamadas al proveedor.

Variables de entorno:

OPENCLAW_GEMINI_OAUTH_CLIENT_ID / GEMINI_CLI_OAUTH_CLIENT_ID
OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET / GEMINI_CLI_OAUTH_CLIENT_SECRET

La detección automática durante la incorporación muestra los inicios de sesión existentes de la CLI de Gemini, pero nunca los prueba automáticamente porque la CLI de Gemini no dispone de una comprobación sin herramientas. Elija el OAuth de la CLI de Gemini o una clave de la API de Gemini para continuar.

Las referencias de modelos google-gemini-cli/* son alias de compatibilidad heredados. Las configuraciones nuevas deben utilizar referencias de modelos google/* junto con el entorno de ejecución google-gemini-cli cuando se quiera ejecutar localmente la CLI de Gemini.

Capacidades

Capacidad	Compatibilidad
Completado de chat	Sí
Generación de imágenes	Sí
Generación de música	Sí
Texto a voz	Sí
Voz en tiempo real	Sí (API Live de Google)
Comprensión de imágenes	Sí
Transcripción de audio	Sí
Comprensión de vídeo	Sí
Búsqueda web (Grounding)	Sí
Pensamiento/razonamiento	Sí (Gemini 2.5+ / Gemini 3+)
Modelos Gemma 4	Sí

Búsqueda web

El proveedor de búsqueda web gemini incluido utiliza el Grounding de Google Search de Gemini. Configure una clave de búsqueda específica en plugins.entries.google.config.webSearch, o permita que reutilice models.providers.google.apiKey después de GEMINI_API_KEY:

json5

{  plugins: {    entries: {      google: {        config: {          webSearch: {            apiKey: "AIza...", // opcional si se establece GEMINI_API_KEY o models.providers.google.apiKey            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // recurre a models.providers.google.baseUrl            model: "gemini-2.5-flash",          },        },      },    },  },}

El orden de prioridad de las credenciales es webSearch.apiKey específica, luego GEMINI_API_KEY y después models.providers.google.apiKey. webSearch.baseUrl es opcional y existe para proxies de operadores o endpoints compatibles con la API de Gemini; cuando se omite, la búsqueda web de Gemini reutiliza models.providers.google.baseUrl. Consulte Búsqueda de Gemini para conocer el comportamiento de la herramienta específico del proveedor.

Tip

Los modelos Gemini 3 utilizan thinkingLevel en lugar de thinkingBudget. OpenClaw asigna los controles de razonamiento de los alias Gemini 3, Gemini 3.1 y gemini-*-latest a thinkingLevel para que las ejecuciones predeterminadas o 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 valor fijo de thinkingLevel para que Google pueda elegir el nivel; Gemini 2.5 envía el valor centinela dinámico thinkingBudget: -1 de Google.

Los modelos Gemma 4 (por ejemplo, gemma-4-26b-a4b-it) admiten el modo de pensamiento. OpenClaw reescribe thinkingBudget como un valor thinkingLevel de Google compatible con Gemma 4. Establecer el pensamiento en off mantiene el pensamiento deshabilitado en lugar de asignarlo a MINIMAL.

Gemini 2.5 Pro solo funciona en modo de pensamiento y rechaza un valor explícito thinkingBudget: 0; OpenClaw elimina ese valor de 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 utiliza de forma predeterminada google/gemini-3.1-flash-image.

También admite google/gemini-3-pro-image
Generación: 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 utilizar Google como proveedor de imágenes predeterminado:

json5

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

Generación de vídeo

El plugin google incluido también registra la generación de vídeo mediante la herramienta compartida video_generate.

Modelo de vídeo predeterminado: google/veo-3.1-fast-generate-preview
Modos: texto a vídeo, imagen a vídeo y flujos de referencia de un solo vídeo
Admite aspectRatio (16:9, 9:16) y resolution (720P, 1080P); actualmente Veo no admite la salida de audio
Duraciones admitidas: 4, 6 u 8 segundos (los demás valores se ajustan al valor permitido más cercano)

Para utilizar Google como proveedor de vídeo predeterminado:

json5

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

Generación de música

El plugin google incluido también registra la 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 del prompt: lyrics y 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 una sesión se desvinculan mediante el flujo compartido de tareas/estado, incluido action: "status"

Para utilizar Google como proveedor de música predeterminado:

json5

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

Texto a voz

El proveedor de voz google incluido utiliza la ruta TTS de la API de Gemini con gemini-3.1-flash-tts-preview.

Voz predeterminada: Kore
Autenticación: tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY o GOOGLE_API_KEY
Salida: WAV para archivos adjuntos TTS normales, Opus para destinos de notas de voz y PCM para Talk/telefonía
Salida de notas de voz: el PCM de Google se encapsula como WAV y se transcodifica a Opus de 48 kHz con ffmpeg

La ruta TTS por lotes de Gemini de Google devuelve el audio generado en la respuesta generateContent completada. Para obtener conversaciones habladas con la menor latencia, utilice el proveedor de voz en tiempo real de Google basado en la API Live de Gemini en lugar del TTS por lotes.

Para utilizar Google como proveedor TTS predeterminado:

json5

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

El TTS de la API de Gemini utiliza instrucciones en lenguaje natural para controlar el estilo. Establezca audioProfile para anteponer una instrucción de estilo reutilizable al texto hablado. Establezca speakerName cuando el texto de la instrucción haga referencia a un hablante con nombre.

El TTS de la API de Gemini también acepta etiquetas de audio expresivas entre corchetes en el texto, como [whispers] o [laughs]. Para que las etiquetas no aparezcan en la respuesta visible del chat pero se envíen al TTS, colóquelas dentro de un bloque [[tts:text]]...[[/tts:text]]:

text

Aquí está el texto limpio de la respuesta. [[tts:text]][whispers] Aquí está la versión hablada.[[/tts:text]]

Voz en tiempo real

El plugin google incluido registra un proveedor de voz en tiempo real basado en la API Live de Gemini para puentes de audio de backend como Voice Call y Google Meet.

Ajuste	Ruta de configuración	Valor predeterminado
Modelo	`plugins.entries.voice-call.config.realtime.providers.google.model`	`gemini-3.1-flash-live-preview`
Voz	`...google.voice`	`Kore`
Temperatura	`...google.temperature`	(sin establecer)
Sensibilidad de inicio de VAD	`...google.startSensitivity`	(sin establecer)
Sensibilidad de fin de VAD	`...google.endSensitivity`	(sin establecer)
Duración del silencio	`...google.silenceDurationMs`	(sin establecer)
Gestión de la actividad	`...google.activityHandling`	Valor predeterminado de Google, `start-of-activity-interrupts`
Cobertura del turno	`...google.turnCoverage`	Valor predeterminado de Google, `audio-activity-and-all-video`
Desactivar VAD automático	`...google.automaticActivityDetectionDisabled`	`false`
Reanudación de sesión	`...google.sessionResumption`	`true`
Compresión del contexto	`...google.contextWindowCompression`	`true`
Clave de API	`...google.apiKey`	Recurre a `models.providers.google.apiKey`, `GEMINI_API_KEY` o `GOOGLE_API_KEY`

Ejemplo de configuración en tiempo real de llamadas 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 la verificación en vivo por parte del mantenedor, ejecute OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. La prueba de humo también cubre las rutas del backend/WebRTC de OpenAI; el tramo de Google genera el mismo formato restringido de token de la API Live que utiliza Talk de la interfaz de control, abre el endpoint WebSocket del navegador, envía la carga útil de configuración inicial junto con un fotograma JPEG y verifica una respuesta de texto y una comunicación bidireccional de la función describe_view.

Configuración avanzada

Reutilización directa de la caché de Gemini

Para ejecuciones directas de la API de Gemini (api: "google-generative-ai"), OpenClaw transmite a las solicitudes de Gemini un identificador cachedContent configurado.

Configure parámetros globales o por modelo mediante cachedContent o la opción heredada cached_content
Los parámetros del ámbito más específico (nivel de modelo sobre global) siempre prevalecen. Dentro del mismo ámbito, si ambas claves están establecidas, prevalece cached_content. Utilice solo una clave por ámbito para evitar resultados inesperados.
Valor de ejemplo: cachedContents/prebuilt-context
El uso de aciertos de caché de Gemini se normaliza en cacheRead de OpenClaw a partir de cachedContentTokenCount del sistema de origen

json5

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

Notas de uso de la CLI de Gemini

Al utilizar el proveedor OAuth google-gemini-cli, OpenClaw usa de forma predeterminada la salida stream-json de la CLI de Gemini y normaliza el uso a partir de la carga útil final stats. Las anulaciones heredadas de --output-format json siguen utilizando el analizador JSON.

El texto de respuesta transmitido procede de los eventos message del asistente.
Para la salida JSON heredada, el texto de respuesta procede del campo response del JSON de la CLI.
El uso recurre a stats cuando la CLI deja vacío usage.
stats.cached se normaliza en cacheRead de OpenClaw.
Si falta stats.input, OpenClaw obtiene los tokens de entrada a partir de stats.input_tokens - stats.cached.

Configuración del entorno y del demonio

Si el Gateway se ejecuta como demonio (launchd/systemd), asegúrese de que GEMINI_API_KEY esté disponible para ese proceso (por ejemplo, en ~/.openclaw/.env o mediante env.shellEnv).

Temas relacionados

Selección de modelos

Selección de proveedores, referencias de modelos y comportamiento de conmutación por error.

Generación de imágenes

Parámetros compartidos de la herramienta de imágenes y selección de proveedores.

Generación de vídeos

Parámetros compartidos de la herramienta de vídeo y selección de proveedores.

Generación de música

Parámetros compartidos de la herramienta de música y selección de proveedores.

Was this useful?

Google (Gemini)

Primeros pasos

Clave de API

Obtener una clave de API

Ejecutar la incorporación

Establecer un modelo predeterminado

Verificar que el modelo esté disponible

CLI de Gemini (OAuth)

Instalar la CLI de Gemini

Iniciar sesión mediante OAuth

Verificar que el modelo esté disponible

Capacidades

Búsqueda web

Generación de imágenes

Generación de vídeo

Generación de música

Texto a voz

Voz en tiempo real

Configuración avanzada

Temas relacionados

On this page

Molty