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 ejecución: agentRuntime.id: "google-gemini-cli" reutiliza OAuth de Gemini CLI y mantiene las referencias de modelos en su forma canónica google/*.

Primeros pasos

Elija su método de autenticación preferido y siga los pasos de configuración.

Clave de API

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

Ejecutar la incorporación

bash

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

También puede proporcionar 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

Gemini CLI (OAuth)

Recomendado para: reutilizar un inicio de sesión existente de Gemini CLI mediante OAuth con PKCE, en lugar de usar una clave de API independiente.

Instalar Gemini CLI

El comando local gemini debe estar disponible en PATH.

bash

# Homebrewbrew install gemini-cli # or 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 de modelo de Gemini 3.1 Pro en la API de Gemini 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

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

Capacidades

Capacidad	Compatible
Finalización de chat	Sí
Generación de imágenes	Sí
Generación de música	Sí
Texto a voz	Sí
Voz en tiempo real	Sí (Google Live API)
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 anclaje con 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...", // 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",          },        },      },    },  },}

El orden de precedencia de las credenciales es webSearch.apiKey específica, después GEMINI_API_KEY y, por último, models.providers.google.apiKey. webSearch.baseUrl es opcional y está destinada a proxies de operadores o endpoints compatibles con la API de Gemini; si se omite, la búsqueda web de Gemini reutiliza models.providers.google.baseUrl. Consulte Búsqueda con 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 Gemini 3, Gemini 3.1 y los alias gemini-*-latest a thinkingLevel, de modo que las ejecuciones predeterminadas o de baja latencia no envíen valores deshabilitados de thinkingBudget.

/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 valor centinela dinámico de Google thinkingBudget: -1.

Los modelos Gemma 4 (por ejemplo, gemma-4-26b-a4b-it) admiten el modo de pensamiento. OpenClaw convierte thinkingBudget en un 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 thinkingBudget: 0 explícito; 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-preview.

También admite google/gemini-3-pro-image-preview
Generación: hasta 4 imágenes por solicitud
Modo de edición: habilitado, con 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-preview",      },    },  },}

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 con una única referencia de vídeo
Admite aspectRatio (16:9, 9:16) y resolution (720P, 1080P); actualmente Veo no admite salida de audio
Duraciones compatibles: 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 e instrumental
Formato de salida: mp3 de forma predeterminada, además de wav con google/lyria-3-pro-preview
Entradas de referencia: hasta 10 imágenes
Las ejecuciones respaldadas por sesiones se desvinculan mediante el flujo compartido de tareas y estados, 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: messages.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 conversaciones/telefonía
Salida de notas de voz: el PCM de Google se encapsula como WAV y se transcodifica a Opus de 48 kHz mediante ffmpeg

La ruta por lotes de TTS 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 Gemini Live API en lugar del TTS por lotes.

Para utilizar Google como proveedor TTS predeterminado:

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

El TTS de la API de Gemini utiliza prompts en lenguaje natural para controlar el estilo. Establezca audioProfile para anteponer un prompt de estilo reutilizable al texto hablado. Establezca speakerName cuando el texto del prompt haga referencia a un hablante por su 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 evitar que las etiquetas aparezcan en la respuesta visible del chat y enviarlas al mismo tiempo al TTS, colóquelas dentro de un bloque [[tts:text]]...[[/tts:text]]:

text

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

Voz en tiempo real

El Plugin google incluido registra un proveedor de voz en tiempo real basado en Gemini Live API 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 finalización de VAD	`...google.endSensitivity`	(sin establecer)
Duración del silencio	`...google.silenceDurationMs`	(sin establecer)
Gestión de 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 de 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 de responsables de mantenimiento, 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 de backend/WebRTC de OpenAI; la parte de Google emite el mismo formato de token restringido de la API Live que utiliza la función Conversación de Control UI, abre el extremo WebSocket del navegador, envía la carga útil de configuración inicial y espera setupComplete.

Configuración avanzada

Direct Gemini cache reuse

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

Configure los parámetros por modelo o globales con cachedContent o el valor heredado cached_content
Los parámetros de un ámbito más específico (nivel de modelo frente a global) siempre tienen prioridad. Dentro del mismo ámbito, si ambas claves están establecidas, cached_content tiene prioridad. Use 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 proveedor

json5

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

Gemini CLI usage notes

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

El texto de la respuesta transmitida procede de los eventos message del asistente.
Para la salida JSON heredada, el texto de la respuesta procede 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 obtiene los tokens de entrada mediante stats.input_tokens - stats.cached.

Environment and daemon setup

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

Contenido relacionado

Model selection

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

Image generation

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

Video generation

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

Music generation

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

Was this useful?

Google (Gemini)

Primeros pasos

Clave de API

Ejecutar la incorporación

Establecer un modelo predeterminado

Verificar que el modelo esté disponible

Gemini CLI (OAuth)

Instalar Gemini CLI

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

Contenido relacionado

On this page

Molty