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 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: Google Gemini API
• Opción de tiempo de ejecución: agents.defaults.agentRuntime.id: "google-gemini-cli" reutiliza OAuth de Gemini CLI y mantiene las referencias de modelos canónicas como google/*.

# Primeros pasos

Elige tu método de autenticación preferido y sigue los pasos de configuración.

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

# Búsqueda web

El proveedor de búsqueda web gemini incluido usa el grounding de Google Search de Gemini. Configura una clave de búsqueda dedicada en plugins.entries.google.config.webSearch, o permite 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 operadores o endpoints compatibles con Gemini API; cuando se omite, la búsqueda web de Gemini reutiliza models.providers.google.baseUrl. Consulta Gemini search para ver el comportamiento de herramienta específico del proveedor.

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

# Generación de video

El Plugin google incluido también registra la generación de video mediante la herramienta compartida video_generate.

• Modelo de video predeterminado: google/veo-3.1-fast-generate-preview
• Modos: texto a video, imagen a video y flujos de referencia de video único
• Admite aspectRatio, resolution y audio
• Límite de duración actual: 4 a 8 segundos

Para usar Google como proveedor de video predeterminado:

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

# 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 encapsula 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",
          voiceName: "Kore",
          audioProfile: "Speak professionally with a calm tone.",
        },
      },
    },
  },
}

Gemini API TTS usa prompts en lenguaje natural para controlar el estilo. Configura audioProfile para anteponer un prompt de estilo reutilizable antes del texto hablado. Configura speakerName cuando el texto del 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]]

# Voz en tiempo real

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

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",
                voice: "Kore",
                activityHandling: "start-of-activity-interrupts",
                turnCoverage: "only-activity",
              },
            },
          },
        },
      },
    },
  },
}

Para la verificación en vivo de mantenedores, ejecuta OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. La parte 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

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

# Relacionado