Providers

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

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

Dapatkan kunci API

Buat kunci gratis di Google AI Studio.

Jalankan orientasi awal

bash

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

Atau teruskan kunci secara langsung:

bash

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

Tetapkan model default

json5

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

Verifikasi bahwa model tersedia

bash

openclaw models list --provider google

Gemini CLI (OAuth)

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

Instal Gemini CLI

Perintah lokal gemini harus tersedia di PATH.

bash

# Homebrewbrew install gemini-cli # or npmnpm install -g @google/gemini-cli

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

Masuk melalui OAuth

bash

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

Verifikasi bahwa model tersedia

bash

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

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.

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:

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

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.

Tip

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:

json5

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

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:

json5

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

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:

json5

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

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:

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

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]]:

text

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

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:

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

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

json5

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

Was this useful?

Google (Gemini)

Memulai

Kunci API

Dapatkan kunci API

Jalankan orientasi awal

Tetapkan model default

Verifikasi bahwa model tersedia

Gemini CLI (OAuth)

Instal Gemini CLI

Masuk melalui OAuth

Verifikasi bahwa model tersedia

Kemampuan

Pencarian web

Pembuatan gambar

Pembuatan video

Pembuatan musik

Teks-ke-ucapan

Suara waktu nyata

Konfigurasi lanjutan

Terkait

On this page

Molty