Google (Gemini)

Plugin Google menyediakan akses ke model Gemini melalui Google AI Studio, serta pembuatan gambar, pemahaman media (gambar/audio/video), text-to-speech, dan pencarian web melalui Gemini Grounding.

Provider: google
Auth: GEMINI_API_KEY atau GOOGLE_API_KEY
API: Google Gemini API
Provider alternatif: google-gemini-cli (OAuth)

Memulai

Pilih metode autentikasi yang Anda inginkan dan ikuti langkah-langkah penyiapannya.

API key
Gemini CLI (OAuth)

Paling cocok untuk: akses API Gemini standar melalui Google AI Studio.

Jalankan onboarding

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

Atau berikan key secara langsung:

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

Tetapkan model default

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

Verifikasi bahwa model tersedia

openclaw models list --provider google

Variabel lingkungan GEMINI_API_KEY dan GOOGLE_API_KEY keduanya didukung. Gunakan mana pun yang sudah Anda konfigurasi.

Paling cocok untuk: menggunakan kembali login Gemini CLI yang sudah ada melalui PKCE OAuth alih-alih key API terpisah.

Provider google-gemini-cli adalah integrasi tidak resmi. Beberapa pengguna melaporkan pembatasan akun saat menggunakan OAuth dengan cara ini. Gunakan dengan risiko Anda sendiri.

Instal Gemini CLI

Perintah lokal gemini harus tersedia di PATH.

# Homebrew
brew install gemini-cli

# atau npm
npm install -g @google/gemini-cli

OpenClaw mendukung instalasi Homebrew dan instalasi npm global, termasuk tata letak Windows/npm yang umum.

Masuk melalui OAuth

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

Verifikasi bahwa model tersedia

openclaw models list --provider google-gemini-cli

Model default: google-gemini-cli/gemini-3-flash-preview
Alias: gemini-cli

Variabel lingkungan:

OPENCLAW_GEMINI_OAUTH_CLIENT_ID
OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET

(Atau varian GEMINI_CLI_*.)

Jika permintaan OAuth Gemini CLI gagal setelah login, tetapkan GOOGLE_CLOUD_PROJECT atau GOOGLE_CLOUD_PROJECT_ID pada host Gateway lalu coba lagi.

Jika login gagal sebelum alur browser dimulai, pastikan perintah lokal gemini sudah terinstal dan ada di PATH.

Provider google-gemini-cli yang hanya OAuth adalah surface inferensi teks yang terpisah. Pembuatan gambar, pemahaman media, dan Gemini Grounding tetap berada pada id provider google.

Kemampuan

Capability	Supported
Chat completions	Ya
Image generation	Ya
Music generation	Ya
Text-to-speech	Ya
Image understanding	Ya
Audio transcription	Ya
Video understanding	Ya
Web search (Grounding)	Ya
Thinking/reasoning	Ya (Gemini 2.5+ / Gemini 3+)
Gemma 4 models	Ya

Model Gemini 3 menggunakan thinkingLevel alih-alih thinkingBudget. OpenClaw memetakan kontrol penalaran untuk alias Gemini 3, Gemini 3.1, dan gemini-*-latest ke thinkingLevel sehingga eksekusi default/latensi-rendah tidak mengirim nilai thinkingBudget yang dinonaktifkan.Model Gemma 4 (misalnya gemma-4-26b-a4b-it) mendukung mode thinking. OpenClaw menulis ulang thinkingBudget menjadi thinkingLevel Google yang didukung untuk Gemma 4. Mengatur thinking ke off mempertahankan thinking tetap dinonaktifkan alih-alih memetakannya ke MINIMAL.

Pembuatan gambar

Provider pembuatan gambar google bawaan secara default menggunakan google/gemini-3.1-flash-image-preview.

Juga mendukung google/gemini-3-pro-image-preview
Generate: hingga 4 gambar per permintaan
Mode edit: diaktifkan, hingga 5 gambar input
Kontrol geometri: size, aspectRatio, dan resolution

Untuk menggunakan Google sebagai provider gambar default:

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

Lihat Image Generation untuk parameter tool bersama, pemilihan provider, dan perilaku failover.

Pembuatan video

Plugin google bawaan juga mendaftarkan pembuatan video melalui tool bersama video_generate.

Model video default: google/veo-3.1-fast-generate-preview
Mode: text-to-video, image-to-video, dan alur referensi video tunggal
Mendukung aspectRatio, resolution, dan audio
Batas durasi saat ini: 4 hingga 8 detik

Untuk menggunakan Google sebagai provider video default:

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

Lihat Video Generation untuk parameter tool bersama, pemilihan provider, dan perilaku failover.

Pembuatan musik

Plugin google bawaan juga mendaftarkan pembuatan musik melalui tool bersama music_generate.

Model musik default: google/lyria-3-clip-preview
Juga mendukung google/lyria-3-pro-preview
Kontrol prompt: lyrics dan instrumental
Format output: mp3 secara default, serta wav pada google/lyria-3-pro-preview
Input referensi: hingga 10 gambar
Eksekusi berbasis sesi dipisahkan melalui alur task/status bersama, termasuk action: "status"

Untuk menggunakan Google sebagai provider musik default:

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

Lihat Music Generation untuk parameter tool bersama, pemilihan provider, dan perilaku failover.

Text-to-speech

Provider speech google bawaan menggunakan jalur Gemini API TTS dengan gemini-3.1-flash-tts-preview.

Suara default: Kore
Auth: messages.tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY, atau GOOGLE_API_KEY
Output: WAV untuk lampiran TTS biasa, PCM untuk Talk/telephony
Output voice note native: tidak didukung pada jalur Gemini API ini karena API mengembalikan PCM, bukan Opus

Untuk menggunakan Google sebagai provider TTS default:

{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          model: "gemini-3.1-flash-tts-preview",
          voiceName: "Kore",
        },
      },
    },
  },
}

Gemini API TTS menerima tag audio ekspresif dalam tanda kurung siku di teks, seperti [whispers] atau [laughs]. Untuk menjaga agar tag tidak muncul di balasan chat yang terlihat sambil tetap mengirimkannya ke TTS, letakkan tag tersebut di dalam blok [[tts:text]]...[[/tts:text]]:

Berikut adalah teks balasan yang bersih.

[[tts:text]][whispers] Berikut adalah versi yang diucapkan.[[/tts:text]]

Key API Google Cloud Console yang dibatasi ke Gemini API valid untuk provider ini. Ini bukan jalur Cloud Text-to-Speech API yang terpisah.

Konfigurasi lanjutan

Penggunaan ulang cache Gemini langsung

Untuk eksekusi Gemini API langsung (api: "google-generative-ai"), OpenClaw meneruskan handle cachedContent yang dikonfigurasi ke permintaan Gemini.

Konfigurasikan parameter per model atau global dengan cachedContent atau cached_content lama
Jika keduanya ada, cachedContent akan diprioritaskan
Contoh nilai: cachedContents/prebuilt-context
Penggunaan cache-hit Gemini dinormalisasi ke OpenClaw cacheRead dari upstream cachedContentTokenCount

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

Catatan penggunaan JSON Gemini CLI

Saat menggunakan provider OAuth google-gemini-cli, OpenClaw menormalisasi output JSON CLI sebagai berikut:

Teks balasan berasal dari field CLI JSON response.
Usage menggunakan fallback ke stats saat CLI membiarkan usage kosong.
stats.cached dinormalisasi menjadi OpenClaw cacheRead.
Jika stats.input tidak ada, OpenClaw menurunkan token input dari stats.input_tokens - stats.cached.

Penyiapan lingkungan dan daemon

Jika Gateway berjalan sebagai daemon (launchd/systemd), pastikan GEMINI_API_KEY tersedia untuk proses tersebut (misalnya, di ~/.openclaw/.env atau melalui env.shellEnv).

Terkait

Pemilihan model

Memilih provider, ref model, dan perilaku failover.

Pembuatan gambar

Parameter tool gambar bersama dan pemilihan provider.

Pembuatan video

Parameter tool video bersama dan pemilihan provider.

Pembuatan musik

Parameter tool musik bersama dan pemilihan provider.

Overview

Concepts and configuration

Providers

Google (Gemini)

Google (Gemini)

Memulai

Kemampuan

Pembuatan gambar

Pembuatan video

Pembuatan musik

Text-to-speech

Konfigurasi lanjutan

Terkait

Pemilihan model

Pembuatan gambar

Pembuatan video

Pembuatan musik

Overview

Concepts and configuration

Providers

​Google (Gemini)

​Memulai

​Kemampuan

​Pembuatan gambar

​Pembuatan video

​Pembuatan musik

​Text-to-speech

​Konfigurasi lanjutan

​Terkait

Pemilihan model

Pembuatan gambar

Pembuatan video

Pembuatan musik

Google (Gemini)

Memulai

Kemampuan

Pembuatan gambar

Pembuatan video

Pembuatan musik

Text-to-speech

Konfigurasi lanjutan

Terkait