Google (Gemini) - OpenClaw

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.

Penyedia: google
Auth: GEMINI_API_KEY atau GOOGLE_API_KEY
API: Google Gemini API
Opsi runtime: provider/model agentRuntime.id: "google-gemini-cli" menggunakan ulang OAuth Gemini CLI sambil mempertahankan referensi model kanonis sebagai google/*.

Memulai

Pilih metode auth yang Anda inginkan dan ikuti langkah penyiapannya.

Kunci API
Gemini CLI (OAuth)

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

Jalankan onboarding

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

Atau berikan kuncinya 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 sama-sama diterima. Gunakan mana pun yang sudah Anda konfigurasi.

Paling cocok untuk: menggunakan ulang login Gemini CLI yang sudah ada melalui PKCE OAuth, alih-alih kunci API terpisah.

Penyedia google-gemini-cli adalah integrasi tidak resmi. Sebagian 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

# or 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

Model default: google/gemini-3.1-pro-preview
Runtime: google-gemini-cli
Alias: gemini-cli

ID model Gemini API untuk Gemini 3.1 Pro adalah gemini-3.1-pro-preview. OpenClaw menerima bentuk yang lebih pendek google/gemini-3.1-pro sebagai alias praktis dan menormalkannya sebelum panggilan penyedia.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.

Referensi model google-gemini-cli/* adalah alias kompatibilitas lama. Konfigurasi baru sebaiknya menggunakan referensi model google/* plus runtime google-gemini-cli saat menginginkan eksekusi Gemini CLI lokal.

Kemampuan

Kemampuan	Didukung
Penyelesaian chat	Ya
Pembuatan gambar	Ya
Pembuatan musik	Ya
Text-to-speech	Ya
Suara realtime	Ya (Google Live API)
Pemahaman gambar	Ya
Transkripsi audio	Ya
Pemahaman video	Ya
Pencarian web (Grounding)	Ya
Berpikir/penalaran	Ya (Gemini 2.5+ / Gemini 3+)
Model Gemma 4	Ya

Pencarian web

Penyedia pencarian web gemini bawaan menggunakan grounding Google Search Gemini. Konfigurasikan kunci pencarian khusus di bawah plugins.entries.google.config.webSearch, atau biarkan menggunakan ulang models.providers.google.apiKey setelah 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",
          },
        },
      },
    },
  },
}

Prioritas kredensial adalah webSearch.apiKey khusus, lalu GEMINI_API_KEY, lalu models.providers.google.apiKey. webSearch.baseUrl bersifat opsional dan ada untuk proxy operator atau endpoint Gemini API yang kompatibel; jika dihilangkan, pencarian web Gemini menggunakan ulang models.providers.google.baseUrl. Lihat Pencarian Gemini untuk perilaku alat khusus penyedia.

Model Gemini 3 menggunakan thinkingLevel, bukan thinkingBudget. OpenClaw memetakan kontrol penalaran alias Gemini 3, Gemini 3.1, dan gemini-*-latest ke thinkingLevel agar eksekusi default/latensi rendah tidak mengirim nilai thinkingBudget yang dinonaktifkan./think adaptive mempertahankan semantik berpikir dinamis Google alih-alih memilih level OpenClaw tetap. Gemini 3 dan Gemini 3.1 menghilangkan thinkingLevel tetap agar Google dapat memilih levelnya; Gemini 2.5 mengirim sentinel dinamis Google thinkingBudget: -1.Model Gemma 4 (misalnya gemma-4-26b-a4b-it) mendukung mode berpikir. OpenClaw menulis ulang thinkingBudget menjadi thinkingLevel Google yang didukung untuk Gemma 4. Mengatur berpikir ke off mempertahankan berpikir dalam keadaan nonaktif alih-alih memetakannya ke MINIMAL.

Pembuatan gambar

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

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

Untuk menggunakan Google sebagai penyedia gambar default:

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

Lihat Pembuatan Gambar untuk parameter alat bersama, pemilihan penyedia, dan perilaku failover.

Pembuatan video

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

Model video default: google/veo-3.1-fast-generate-preview
Mode: alur teks-ke-video, gambar-ke-video, dan referensi video tunggal
Mendukung aspectRatio (16:9, 9:16) dan resolution (720P, 1080P); output audio tidak didukung oleh Veo saat ini
Durasi yang didukung: 4, 6, atau 8 detik (nilai lain dibulatkan ke nilai terdekat yang diizinkan)

Untuk menggunakan Google sebagai penyedia video default:

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

Lihat Pembuatan Video untuk parameter alat bersama, pemilihan penyedia, dan perilaku failover.

Pembuatan musik

Plugin google bawaan juga mendaftarkan pembuatan musik melalui alat 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, plus wav pada google/lyria-3-pro-preview
Input referensi: hingga 10 gambar
Eksekusi berbasis sesi dilepaskan melalui alur tugas/status bersama, termasuk action: "status"

Untuk menggunakan Google sebagai penyedia musik default:

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

Lihat Pembuatan Musik untuk parameter alat bersama, pemilihan penyedia, dan perilaku failover.

Text-to-speech

Penyedia ucapan google bawaan menggunakan jalur TTS Gemini API 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 reguler, Opus untuk target catatan suara, PCM untuk Talk/telephony
Output catatan suara: PCM Google dibungkus sebagai WAV dan ditranskode menjadi Opus 48 kHz dengan ffmpeg

Jalur batch Gemini TTS Google mengembalikan audio yang dibuat dalam respons generateContent yang selesai. Untuk percakapan lisan dengan latensi terendah, gunakan penyedia suara realtime Google yang didukung oleh Gemini Live API, bukan TTS batch. Untuk menggunakan Google sebagai penyedia TTS default:

{
  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 menggunakan prompting bahasa alami untuk kontrol gaya. Atur audioProfile untuk menambahkan prompt gaya yang dapat digunakan ulang sebelum teks lisan. Atur speakerName saat teks prompt Anda merujuk ke pembicara bernama. Gemini API TTS juga menerima tag audio kurung siku yang ekspresif di dalam teks, seperti [whispers] atau [laughs]. Agar tag tidak muncul di balasan chat yang terlihat sambil tetap mengirimkannya ke TTS, letakkan tag di dalam blok [[tts:text]]...[[/tts:text]]:

Here is the clean reply text.

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

Kunci API Google Cloud Console yang dibatasi untuk Gemini API valid untuk penyedia ini. Ini bukan jalur Cloud Text-to-Speech API yang terpisah.

Suara realtime

Plugin google bawaan mendaftarkan penyedia suara realtime yang didukung oleh Gemini Live API untuk bridge audio backend seperti Voice Call dan Google Meet.

Pengaturan	Jalur konfigurasi	Default
Model	`plugins.entries.voice-call.config.realtime.providers.google.model`	`gemini-2.5-flash-native-audio-preview-12-2025`
Suara	`...google.voice`	`Kore`
Temperature	`...google.temperature`	(belum diatur)
Sensitivitas awal VAD	`...google.startSensitivity`	(belum diatur)
Sensitivitas akhir VAD	`...google.endSensitivity`	(belum diatur)
Durasi hening	`...google.silenceDurationMs`	(belum diatur)
Penanganan aktivitas	`...google.activityHandling`	Default Google, `start-of-activity-interrupts`
Cakupan giliran	`...google.turnCoverage`	Default Google, `only-activity`
Nonaktifkan VAD otomatis	`...google.automaticActivityDetectionDisabled`	`false`
Pelanjutan sesi	`...google.sessionResumption`	`true`
Kompresi konteks	`...google.contextWindowCompression`	`true`
Kunci API	`...google.apiKey`	Beralih ke `models.providers.google.apiKey`, `GEMINI_API_KEY`, atau `GOOGLE_API_KEY`

Contoh konfigurasi realtime 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 menggunakan audio dua arah dan pemanggilan fungsi melalui WebSocket. OpenClaw menyesuaikan audio bridge telephony/Meet ke stream PCM Live API Gemini dan menjaga panggilan tool pada kontrak suara realtime bersama. Biarkan temperature tidak diatur kecuali Anda memerlukan perubahan sampling; OpenClaw menghilangkan nilai non-positif karena Google Live dapat mengembalikan transkrip tanpa audio untuk temperature: 0. Transkripsi Gemini API diaktifkan tanpa languageCodes; SDK Google saat ini menolak petunjuk kode bahasa pada jalur API ini.

Control UI Talk mendukung sesi browser Google Live dengan token sekali pakai yang dibatasi. Penyedia suara realtime khusus backend juga dapat berjalan melalui transport relay Gateway generik, yang menjaga kredensial penyedia tetap berada di Gateway.

Untuk verifikasi live oleh maintainer, jalankan OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. Smoke test ini juga mencakup jalur backend/WebRTC OpenAI; bagian Google membuat bentuk token Live API terbatas yang sama dengan yang digunakan oleh Control UI Talk, membuka endpoint WebSocket browser, mengirim payload penyiapan awal, dan menunggu setupComplete.

Konfigurasi lanjutan

Direct Gemini cache reuse

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 yang berlaku
Contoh nilai: cachedContents/prebuilt-context
Penggunaan cache-hit Gemini dinormalisasi ke OpenClaw cacheRead dari cachedContentTokenCount upstream

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

Gemini CLI usage notes

Saat menggunakan penyedia OAuth google-gemini-cli, OpenClaw menggunakan output stream-json Gemini CLI secara default dan menormalisasi penggunaan dari payload stats akhir. Override --output-format json lama tetap menggunakan parser JSON.

Teks balasan streaming berasal dari event message asisten.
Untuk output JSON lama, teks balasan berasal dari field response JSON CLI.
Penggunaan beralih ke stats saat CLI membiarkan usage kosong.
stats.cached dinormalisasi ke OpenClaw cacheRead.
Jika stats.input tidak ada, OpenClaw menurunkan token input dari stats.input_tokens - stats.cached.

Environment and daemon setup

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

Terkait

Model selection

Memilih penyedia, referensi model, dan perilaku failover.

Image generation

Parameter tool gambar bersama dan pemilihan penyedia.

Video generation

Parameter tool video bersama dan pemilihan penyedia.

Music generation

Parameter tool musik bersama dan pemilihan penyedia.

​Memulai

​Kemampuan

​Pencarian web

​Pembuatan gambar

​Pembuatan video

​Pembuatan musik

​Text-to-speech

​Suara realtime

​Konfigurasi lanjutan

​Terkait

Model selection

Image generation

Video generation

Music generation

Memulai

Kemampuan

Pencarian web

Pembuatan gambar

Pembuatan video

Pembuatan musik

Text-to-speech

Suara realtime

Konfigurasi lanjutan

Terkait