Google (Gemini)

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

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

Memulai

Pilih metode autentikasi yang diinginkan dan ikuti langkah-langkah penyiapannya.

Kunci API
Gemini CLI (OAuth)

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

Dapatkan kunci API

Buat kunci gratis di Google AI Studio.

Jalankan orientasi awal

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

Atau teruskan kunci 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

GEMINI_API_KEY dan GOOGLE_API_KEY keduanya diterima. Gunakan yang sudah dikonfigurasi.

Paling sesuai untuk: masuk dengan akun Google melalui OAuth Gemini CLI, alih-alih menggunakan kunci API terpisah.

Penyedia google-gemini-cli merupakan integrasi tidak resmi. Beberapa pengguna melaporkan pembatasan akun saat menggunakan OAuth dengan cara ini. Gunakan dengan risiko 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 google/gemini-3.1-pro yang lebih pendek sebagai alias praktis dan menormalisasinya sebelum pemanggilan penyedia.Variabel lingkungan:

OPENCLAW_GEMINI_OAUTH_CLIENT_ID / GEMINI_CLI_OAUTH_CLIENT_ID
OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET / GEMINI_CLI_OAUTH_CLIENT_SECRET

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

Jika proses masuk gagal sebelum alur peramban dimulai, pastikan perintah lokal gemini telah diinstal dan tersedia di PATH.

Deteksi otomatis orientasi awal mencantumkan sesi masuk Gemini CLI yang sudah ada, tetapi tidak pernah mengujinya secara otomatis karena Gemini CLI tidak memiliki pemeriksaan tanpa alat. Pilih OAuth Gemini CLI atau kunci Gemini API untuk melanjutkan.Referensi model google-gemini-cli/* merupakan alias kompatibilitas lama. Konfigurasi baru sebaiknya menggunakan referensi model google/* beserta runtime google-gemini-cli jika menginginkan eksekusi Gemini CLI lokal.

google/gemini-3-pro-preview dihentikan pada 2026-03-09; gunakan google/gemini-3.1-pro-preview sebagai gantinya. Menjalankan ulang penyiapan kunci Gemini API (openclaw onboard --auth-choice gemini-api-key atau openclaw models auth login --provider google) menulis ulang model default lama yang dikonfigurasi menjadi model saat ini.

Kemampuan

Kemampuan	Didukung
Penyelesaian percakapan	Ya
Pembuatan gambar	Ya
Pembuatan musik	Ya
Teks-ke-ucapan	Ya
Suara waktu nyata	Ya (Google Live API)
Pemahaman gambar	Ya
Transkripsi audio	Ya
Pemahaman video	Ya
Pencarian web (Grounding)	Ya
Pemikiran/penalaran	Ya (Gemini 2.5+ / Gemini 3+)
Model Gemma 4	Ya

Pencarian web

Penyedia pencarian web gemini yang disertakan menggunakan grounding Google Search dari Gemini. Konfigurasikan kunci pencarian khusus di bawah plugins.entries.google.config.webSearch, atau biarkan kunci tersebut menggunakan kembali 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",
          },
        },
      },
    },
  },
}

Urutan prioritas kredensial adalah webSearch.apiKey khusus, lalu GEMINI_API_KEY, kemudian models.providers.google.apiKey. webSearch.baseUrl bersifat opsional dan disediakan untuk proksi operator atau endpoint Gemini API yang kompatibel; jika dihilangkan, pencarian web Gemini menggunakan kembali models.providers.google.baseUrl. Lihat Pencarian Gemini untuk perilaku alat khusus penyedia.

Model Gemini 3 menggunakan thinkingLevel, bukan thinkingBudget. OpenClaw memetakan kontrol penalaran Gemini 3, Gemini 3.1, dan alias gemini-*-latest ke thinkingLevel agar proses default/latensi rendah tidak mengirim nilai thinkingBudget yang dinonaktifkan./think adaptive mempertahankan semantik pemikiran dinamis Google, alih-alih memilih tingkat OpenClaw tetap. Gemini 3 dan Gemini 3.1 tidak menyertakan thinkingLevel tetap sehingga Google dapat memilih tingkatnya; Gemini 2.5 mengirim sentinel dinamis Google thinkingBudget: -1.Model Gemma 4 (misalnya gemma-4-26b-a4b-it) mendukung mode pemikiran. OpenClaw menulis ulang thinkingBudget menjadi thinkingLevel Google yang didukung untuk Gemma 4. Menetapkan pemikiran ke off mempertahankan pemikiran tetap dinonaktifkan, alih-alih memetakannya ke MINIMAL.Gemini 2.5 Pro hanya berfungsi dalam mode pemikiran dan menolak thinkingBudget: 0 eksplisit; OpenClaw menghapus nilai tersebut dari permintaan Gemini 2.5 Pro, alih-alih mengirimkannya.

Pembuatan gambar

Penyedia pembuatan gambar google yang disertakan secara default menggunakan google/gemini-3.1-flash-image.

Juga mendukung google/gemini-3-pro-image
Pembuatan: hingga 4 gambar per permintaan
Mode penyuntingan: diaktifkan, hingga 5 gambar masukan
Kontrol geometri: size, aspectRatio, dan resolution

Untuk menggunakan Google sebagai penyedia gambar default:

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

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

Pembuatan video

Plugin google yang disertakan juga mendaftarkan pembuatan video melalui alat bersama video_generate.

Model video default: google/veo-3.1-fast-generate-preview
Mode: teks-ke-video, gambar-ke-video, dan alur referensi satu video
Mendukung aspectRatio (16:9, 9:16) dan resolution (720P, 1080P); keluaran audio saat ini tidak didukung oleh Veo
Durasi yang didukung: 4, 6, atau 8 detik (nilai lain disesuaikan 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 yang disertakan 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 perintah: lyrics dan instrumental
Format keluaran: mp3 secara default, serta wav pada google/lyria-3-pro-preview
Masukan referensi: hingga 10 gambar
Proses berbasis sesi dilepas 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.

Teks-ke-ucapan

Penyedia ucapan google yang disertakan menggunakan jalur TTS Gemini API dengan gemini-3.1-flash-tts-preview.

Suara default: Kore
Autentikasi: messages.tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY, atau GOOGLE_API_KEY
Keluaran: WAV untuk lampiran TTS biasa, Opus untuk target catatan suara, PCM untuk Talk/telefoni
Keluaran catatan suara: PCM Google dibungkus sebagai WAV dan ditranskode menjadi Opus 48 kHz dengan ffmpeg

Jalur TTS Gemini batch Google mengembalikan audio yang dihasilkan dalam respons generateContent yang telah selesai. Untuk percakapan lisan dengan latensi terendah, gunakan penyedia suara waktu nyata 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.",
        },
      },
    },
  },
}

TTS Gemini API menggunakan perintah bahasa alami untuk mengontrol gaya. Tetapkan audioProfile untuk menambahkan perintah gaya yang dapat digunakan kembali sebelum teks yang diucapkan. Tetapkan speakerName jika teks perintah merujuk pada pembicara bernama. TTS Gemini API juga menerima tag audio ekspresif dalam tanda kurung siku di dalam teks, seperti [whispers] atau [laughs]. Agar tag tidak muncul dalam balasan percakapan yang terlihat sekaligus tetap dikirim 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]]

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

Suara waktu nyata

Plugin google yang disertakan mendaftarkan penyedia suara waktu nyata yang didukung oleh Gemini Live API untuk jembatan audio backend seperti Voice Call dan Google Meet.

Pengaturan	Jalur konfigurasi	Default
Model	`plugins.entries.voice-call.config.realtime.providers.google.model`	`gemini-3.1-flash-live-preview`
Suara	`...google.voice`	`Kore`
Suhu	`...google.temperature`	(tidak ditetapkan)
Sensitivitas awal VAD	`...google.startSensitivity`	(tidak ditetapkan)
Sensitivitas akhir VAD	`...google.endSensitivity`	(tidak ditetapkan)
Durasi keheningan	`...google.silenceDurationMs`	(tidak ditetapkan)
Penanganan aktivitas	`...google.activityHandling`	Default Google, `start-of-activity-interrupts`
Cakupan giliran	`...google.turnCoverage`	Default Google, `audio-activity-and-all-video`
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 waktu nyata Panggilan Suara:

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

Google Live API menggunakan audio dua arah dan pemanggilan fungsi melalui WebSocket. OpenClaw menyesuaikan audio jembatan telepon/Meet ke aliran PCM Live API Gemini dan mempertahankan pemanggilan alat pada kontrak suara waktu nyata bersama. Biarkan temperature tidak ditetapkan kecuali Anda perlu mengubah pengambilan sampel; OpenClaw menghilangkan nilai nonpositif 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.

Gemini 3.1 Live menerima teks percakapan melalui input waktu nyata dan menggunakan pemanggilan fungsi berurutan. OpenClaw menghilangkan NON_BLOCKING, penjadwalan respons fungsi, dan bidang dialog afektif yang lebih lama untuk model ini. Utamakan thinkingLevel; nilai positif thinkingBudget yang dikonfigurasi dipetakan ke tingkat terdekat yang didukung, sedangkan -1 mempertahankan default Google. Lihat perbandingan kemampuan Gemini Live.

Talk di Control UI mendukung sesi browser Google Live dengan token sekali pakai yang dibatasi. Dalam Video Talk, browser mengirim frame JPEG terbatas secara langsung ke Google Live pada batas maksimum penyedia, yaitu satu frame per detik. Fungsi describe_view melaporkan apakah aliran kamera tersebut aktif. Frame kamera tidak melewati Gateway. Penyedia suara waktu nyata khusus backend juga dapat berjalan melalui transportasi relai Gateway generik, yang menyimpan kredensial penyedia di Gateway.

Untuk verifikasi langsung oleh pengelola, 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 token Live API terbatas dengan bentuk yang sama seperti yang digunakan Talk di Control UI, membuka endpoint WebSocket browser, mengirim payload penyiapan awal beserta satu frame JPEG, dan memverifikasi respons teks serta perjalanan pulang-pergi fungsi describe_view.

Konfigurasi lanjutan

Penggunaan ulang cache Gemini secara langsung

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

Konfigurasikan parameter per model atau global dengan cachedContent atau cached_content versi lama
Parameter dari cakupan yang lebih spesifik (tingkat model di atas global) selalu diutamakan. Dalam cakupan yang sama, jika kedua kunci ditetapkan, cached_content diutamakan. Gunakan hanya satu kunci per cakupan untuk menghindari hasil yang tidak terduga.
Contoh nilai: cachedContents/prebuilt-context
Penggunaan cache-hit Gemini dinormalisasi ke cacheRead OpenClaw dari cachedContentTokenCount hulu

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

Catatan penggunaan Gemini CLI

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

Teks balasan yang dialirkan berasal dari peristiwa message asisten.
Untuk output JSON versi lama, teks balasan berasal dari bidang response JSON CLI.
Penggunaan beralih ke stats ketika CLI membiarkan usage kosong.
stats.cached dinormalisasi ke cacheRead OpenClaw.
Jika stats.input tidak tersedia, OpenClaw memperoleh token input dari stats.input_tokens - stats.cached.

Penyiapan lingkungan dan daemon

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

Terkait

Pemilihan model

Memilih penyedia, referensi model, dan perilaku failover.

Pembuatan gambar

Parameter alat gambar bersama dan pemilihan penyedia.

Pembuatan video

Parameter alat video bersama dan pemilihan penyedia.

Pembuatan musik

Parameter alat musik bersama dan pemilihan penyedia.

Overview

Concepts and configuration

Providers

Memulai

Kemampuan

Pencarian web

Pembuatan gambar

Pembuatan video

Pembuatan musik

Teks-ke-ucapan

Suara waktu nyata

Konfigurasi lanjutan

Terkait

Pemilihan model

Pembuatan gambar

Pembuatan video

Pembuatan musik

​Memulai

​Kemampuan

​Pencarian web

​Pembuatan gambar

​Pembuatan video

​Pembuatan musik

​Teks-ke-ucapan

​Suara waktu nyata

​Konfigurasi lanjutan

​Terkait

Pemilihan model

Pembuatan gambar

Pembuatan video

Pembuatan musik

Memulai

Kemampuan

Pencarian web

Pembuatan gambar

Pembuatan video

Pembuatan musik

Teks-ke-ucapan

Suara waktu nyata

Konfigurasi lanjutan

Terkait