OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

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 Anda inginkan dan ikuti langkah-langkah penyiapannya.

Kunci API

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

  • Jalankan orientasi awal

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

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

  • Pastikan model tersedia

    bash
    openclaw models list --provider google

    • Gemini CLI (OAuth)

    Paling sesuai untuk: menggunakan kembali proses masuk Gemini CLI yang sudah ada melalui OAuth PKCE, alih-alih kunci API terpisah.

  • Instal Gemini CLI

    Perintah lokal gemini harus tersedia di PATH.

    bash
    # Homebrewbrew install gemini-cli # atau 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

  • Pastikan 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 singkat sebagai alias praktis dan menormalisasinya sebelum memanggil penyedia.

    Variabel lingkungan:

    • OPENCLAW_GEMINI_OAUTH_CLIENT_ID / GEMINI_CLI_OAUTH_CLIENT_ID
    • OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET / GEMINI_CLI_OAUTH_CLIENT_SECRET

    Referensi model google-gemini-cli/* adalah 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 bawaan menggunakan grounding Google Search dari Gemini. Konfigurasikan kunci pencarian khusus pada 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...", // opsional jika GEMINI_API_KEY atau models.providers.google.apiKey ditetapkan            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // menggunakan models.providers.google.baseUrl sebagai cadangan            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 titik akhir Gemini API yang kompatibel; jika dihilangkan, pencarian web Gemini menggunakan kembali models.providers.google.baseUrl. Lihat Pencarian Gemini untuk perilaku alat yang khusus bagi penyedia.

    Pembuatan gambar

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

    • Juga mendukung google/gemini-3-pro-image-preview
    • 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-preview",      },    },  },}

    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: 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 yang diizinkan dan paling dekat)

    Untuk menggunakan Google sebagai penyedia video default:

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

    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 perintah: lyrics dan instrumental
    • Format keluaran: mp3 secara default, serta wav pada google/lyria-3-pro-preview
    • Masukan referensi: hingga 10 gambar
    • Eksekusi yang didukung 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 bawaan 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 suara 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: "Bicaralah secara profesional dengan nada tenang.",        },      },    },  },}

    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 Anda merujuk pada pembicara bernama.

    TTS Gemini API juga menerima tag audio ekspresif dalam tanda kurung siku di dalam teks, seperti [berbisik] atau [tertawa]. Agar tag tidak muncul dalam balasan percakapan tetapi tetap dikirim ke TTS, tempatkan tag tersebut di dalam blok [[tts:text]]...[[/tts:text]]:

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

    Suara waktu nyata

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

    Pengaturan Jalur konfigurasi Bawaan
    Model plugins.entries.voice-call.config.realtime.providers.google.model gemini-3.1-flash-live-preview
    Suara ...google.voice Kore
    Suhu ...google.temperature (tidak diatur)
    Sensitivitas awal VAD ...google.startSensitivity (tidak diatur)
    Sensitivitas akhir VAD ...google.endSensitivity (tidak diatur)
    Durasi keheningan ...google.silenceDurationMs (tidak diatur)
    Penanganan aktivitas ...google.activityHandling Bawaan Google, start-of-activity-interrupts
    Cakupan giliran ...google.turnCoverage Bawaan 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 Menggunakan models.providers.google.apiKey, GEMINI_API_KEY, atau GOOGLE_API_KEY sebagai cadangan

    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. Uji asap ini juga mencakup jalur backend/WebRTC OpenAI; bagian Google menerbitkan bentuk token Live API terbatas yang sama dengan yang digunakan oleh fitur Percakapan di UI Kontrol, membuka titik akhir WebSocket peramban, mengirim muatan penyiapan awal, dan menunggu setupComplete.

    Konfigurasi lanjutan

    Penggunaan kembali cache Gemini secara langsung

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

    • Konfigurasikan parameter per model atau global menggunakan cachedContent atau cached_content lama
    • Parameter dari cakupan yang lebih spesifik (tingkat model dibandingkan 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 Gemini yang berhasil dinormalisasi menjadi 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 keluaran stream-json Gemini CLI secara bawaan dan menormalisasi penggunaan dari muatan akhir stats. Penimpaan lama --output-format json tetap menggunakan pengurai JSON.

    • Teks balasan yang dialirkan berasal dari peristiwa message asisten.
    • Untuk keluaran JSON lama, teks balasan berasal dari bidang response pada JSON CLI.
    • Penggunaan menggunakan stats sebagai cadangan saat CLI membiarkan usage kosong.
    • stats.cached dinormalisasi menjadi cacheRead OpenClaw.
    • Jika stats.input tidak tersedia, OpenClaw memperoleh jumlah token masukan 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 pengalihan kegagalan.
    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?
    On this page

    On this page