OpenClaw dengan Gemini: penyiapan model, kunci API, dan pemeriksaan biaya

OpenClaw mengakses Gemini melalui plugin google bawaannya: tetapkan GEMINI_API_KEY atau GOOGLE_API_KEY, jalankan openclaw onboard --auth-choice gemini-api-key, lalu tetapkan model secara eksplisit — karena menambahkan autentikasi tidak mengubah model default Anda. Bagian yang paling sering terlewat dalam postingan setup adalah bahwa dengan kunci AI Studio, OpenClaw memiliki tiga permukaan Gemini terpisah, masing-masing dengan kredensial, endpoint, dan tagihannya sendiri. (Vertex AI adalah jalur kredensial keempat yang terpisah melalui gcloud Application Default Credentials, dan tidak dibahas di sini.) Membuat chat berfungsi tidak mengaktifkan penelusuran Gemini, dan mengaktifkan penelusuran Gemini dapat membebankan biaya ke project Google yang tidak pernah disentuh oleh rute chat Anda.

Integrasi Gemini bukan instalasi terpisah. Integrasi ini sudah disertakan di dalam OpenClaw sebagai plugin provider google bawaan (plugin provider resmi, 21 September 2026), dan OpenClaw berlisensi MIT serta diterbitkan sebagai openclaw@2026.9.5 di npm, yang memerlukan Node >=24.16.0 <25 || >=26.1.0 (registri npm, 21 September 2026). Perangkat lunaknya gratis; semua hal di bawah ini membahas biaya kuncinya.

Tiga permukaan Gemini, tiga kredensial

Aturan prioritasnya adalah bagian yang berguna. Penelusuran web Gemini membaca plugins.entries.google.config.webSearch.apiKey terlebih dahulu, lalu GEMINI_API_KEY, kemudian models.providers.google.apiKey, dan webSearch.baseUrl khusus memiliki prioritas sebelum models.providers.google.baseUrl. OpenClaw juga tidak mewarisi header provider model di sini, karena header tersebut "milik endpoint provider model, yang dapat berbeda dari endpoint penelusuran web", serta mempertahankan kepemilikan Content-Type, x-goog-api-key, dan x-goog-api-client pada permintaan penelusuran (dokumen penelusuran Gemini, 21 September 2026). Dua rute, sengaja independen.

Sebelum mengikuti tutorial lama: OpenClaw menyatakan bahwa OpenClaw "tidak menawarkan setup OAuth Gemini CLI atau OAuth Antigravity baru", dengan merujuk pada berakhirnya Login Gemini CLI konsumen dengan akses Google pada 18 Juni 2026 (dokumen provider). Postingan Google sendiri pada 19 Mei 2026 menyatakan bahwa ekstensi Gemini CLI dan Code Assist IDE berhenti melayani pelanggan Google AI Pro dan Ultra serta pengguna gratis (blog developer Google). Kedua pernyataan tersebut membahas CLI dan permukaan IDE, bukan kunci API AI Studio — jalur kunci API adalah yang dijelaskan di bawah.

Menetapkan kunci API Gemini

# The bundled google plugin reads either name.
export GEMINI_API_KEY="AIza..."   # or GOOGLE_API_KEY

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

# Auth alone does not change the default model — set it on purpose.
openclaw models list --provider google
openclaw models set google/<id-from-that-list>

Plugin bawaan juga membaca GEMINI_API_KEYS, GEMINI_API_KEY_1, dan GEMINI_API_KEY_2 untuk rotasi serta OPENCLAW_LIVE_GEMINI_KEY sebagai satu pengesampingan (plugin provider resmi, 21 September 2026). Variabel tersebut didokumentasikan sebagai milik plugin google; referensi custom-provider tidak mencantumkannya untuk id provider yang Anda deklarasikan sendiri, yang menetapkan kuncinya melalui apiKey (ekspansi $${ENV_VAR} ditampilkan di sana).

Baris terakhir lebih penting daripada yang terlihat. openclaw configure "mempertahankan agents.defaults.model.primary yang sudah ada saat Anda menambahkan atau mengautentikasi ulang provider", dan openclaw models auth login melakukan hal yang sama kecuali Anda meneruskan --set-default (aturan cepat). Mengautentikasi Gemini tetapi tetap mendapatkan jawaban dari model lama adalah perilaku yang diharapkan, bukan bug.

Jangan menyalin id model dari tutorial mana pun, termasuk yang ini. Dengan kunci yang dikonfigurasi, OpenClaw menyegarkan katalog model teks Google AI Studio dari API Gemini models.list, sehingga varian baru muncul tanpa rilis OpenClaw — dan halaman OpenClaw sendiri tidak konsisten mengenai id contoh, menyebut google/gemini-3.5-flash di satu tempat, google/gemini-3.1-flash dan google/gemini-3.1-pro-preview di tempat lain, serta menetapkan alat penelusuran ke gemini-3.6-flash secara default. Daftar langsung adalah satu-satunya sumber otoritatif. OpenClaw memang menormalisasi beberapa ref lama — google/gemini-3.1-pro "diterima dan dinormalisasi" menjadi google/gemini-3.1-pro-preview (plugin provider resmi) — dan google/gemini-3-pro-preview "dipensiunkan pada 2026-03-09", dengan google/gemini-3.1-pro-preview disebut sebagai penggantinya (dokumen provider, 21 September 2026).

Apa yang sebenarnya ditagihkan oleh kunci API Gemini

Token dan grounding penelusuran adalah dua item tagihan, dan halaman Google sekilas tampak seperti satu item. Tarif Gemini Developer API tingkat Standard per 1 juta token, dari halaman harga Google (terakhir diperbarui 16 September 2026, dibaca 21 September 2026):

Baca kolom terakhir dua kali. Model penelusuran web Gemini default OpenClaw adalah gemini-3.6-flash, model Gemini 3.x yang grounding-nya "Tidak tersedia" pada tingkat gratis Google — jadi setup penelusuran Gemini siap pakai memerlukan project yang ditagihkan meskipun token model yang sama gratis. Satuannya juga berbeda: OpenClaw sendiri mencatat bahwa "Grounding Gemini 3 ditagihkan per kueri penelusuran, sedangkan grounding Gemini 2.5 ditagihkan per prompt", dan Google menambahkan bahwa satu permintaan "dapat menghasilkan satu atau beberapa kueri ke Google Search. Anda akan ditagih untuk setiap kueri penelusuran individual yang dilakukan". Grounding berada di atas biaya token — "Biaya untuk Gemini selalu berlaku" (kedua kutipan berasal dari halaman harga yang sama). Sebagai ilustrasi, sebulan dengan 6.500 kueri penelusuran Gemini 3.x menagihkan 1.500 di antaranya dengan tarif $14 per 1.000, atau $21,00 hanya untuk biaya penelusuran, sebelum token apa pun.

Dua input tambahan dari halaman yang sama: tingkat berbayar menambahkan caching konteks dan Batch API dengan pengurangan biaya 50%, serta membalik poin penggunaan data — konten tingkat gratis "digunakan untuk meningkatkan produk kami", sedangkan konten berbayar tidak, yang penting bagi asisten yang selalu aktif. Gemini juga hanya salah satu provider penelusuran OpenClaw; DuckDuckGo ("Tidak ada (tanpa kunci)"), SearXNG ("Tidak ada (dihosting sendiri)"), dan Parallel Search (Gratis) ("Tidak ada (MCP gratis)") tercantum sebagai opsi tanpa kunci dalam tabel provider penelusuran webnya (penelusuran web, 21 September 2026), jadi pertanyaan "apakah saya sama sekali memerlukan grounding Gemini" adalah pertanyaan awal yang wajar.

Merutekan chat Gemini melalui gateway yang kompatibel dengan OpenAI

Referensi custom-provider OpenClaw menyatakan bahwa gunakan entri models.providers.<id> eksplisit "hanya jika Anda ingin mengganti URL dasar, header, atau daftar model default", dan referensi konfigurasi gateway mencantumkan sebelas nilai api: openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, pi-messages, dan azure-openai-responses. Skema konfigurasi pada v2026.9.7 menerima nilai kedua belas, google-interactions, yang ditambahkan pada 25 September 2026. Referensi tersebut belum mencantumkannya, tetapi halaman provider Google OpenClaw mendokumentasikannya sebagai alternatif opt-in untuk transport google-generative-ai default, menggunakan Interactions API Gemini di bawah https://generativelanguage.googleapis.com/v1beta. Model Gemini Kunavo diakses melalui permukaannya yang kompatibel dengan OpenAI di POST /v1/chat/completions (endpoint chat), dan Kunavo tidak menerbitkan generativelanguage, v1beta, atau endpoint Interactions — jadi tidak ada adapter Google yang dapat menjangkaunya, dan rute yang dapat dijangkau adalah id provider terpisah, bukan plugin google yang dialihkan.

{
  "models": {
    "mode": "merge",
    "providers": {
      "kunavo": {
        "baseUrl": "https://api.kunavo.com/v1",
        "apiKey": "${KUNAVO_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gemini-3-8-flash",
            "name": "Gemini 3.8 Flash",
            "input": [
              "text",
              "image"
            ],
            "contextWindow": 1048576,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "kunavo/gemini-3-8-flash"
      }
    }
  }
}

Ada empat detail yang sangat menentukan. Slug-nya menggunakan tanda hubung — id Kunavo adalah gemini-3-8-flash, sedangkan milik Google dan OpenClaw menggunakan titik, dan keduanya merupakan string yang berbeda. contextWindow dideklarasikan karena model khusus tanpa metadata konteks akan kembali ke anggaran 200.000 token, sehingga sebagian besar jendela yang dicatat katalog Kunavo di sini terbuang (1.048.576 token — metadata Kunavo, bukan batas yang diterbitkan Google). input menyebutkan gambar karena OpenClaw menetapkan model khusus hanya ke teks secara default. Dan cost dihilangkan, sehingga estimasi lokal OpenClaw default ke nol pada rute ini: tampilan $0 berarti metadata tidak ada, bukan inferensi gratis.

Hal yang dikorbankan oleh rute ini didokumentasikan, bukan ditebak. Pada api: "openai-completions" terhadap host yang bukan milik OpenAI sendiri, OpenClaw memaksa compat.supportsDeveloperRole: false dan melewati pembentukan permintaan native — tanpa service_tier, tanpa store Responses atau Completions, tanpa petunjuk prompt-cache, dan tanpa pembentukan payload yang kompatibel dengan reasoning (custom provider). Ekstra khusus Gemini juga tetap tidak tersedia: params.cachedContent didokumentasikan untuk eksekusi Gemini langsung, variabel rotasi kunci adalah fitur plugin, dan pemetaan thinkingLevel / thinkingBudget OpenClaw dijelaskan untuk provider google — apakah pemetaan itu tetap berfungsi melalui rute gateway bukan sesuatu yang diverifikasi halaman ini.

Kunavo tidak menyediakan model embedding maupun model text-to-speech atau speech-to-text. Karena itu, kontrak embedding dan speech plugin google tetap menggunakan kunci Google, terlepas dari bagaimana chat dirutekan.

Untuk kapabilitas, berhati-hatilah dalam mempercayai siapa. Halaman model Google saat ini tidak lagi menampilkan batas token per model, sehingga angka konteks yang dikutip di tempat lain adalah salinan seseorang dari sumber lama. Katalog Kunavo menandai vision, function calling, streaming, dan konteks panjang pada daftar Gemini-nya, serta thinking pada semua model kecuali gemini-2-5-flash. Setiap klaim terbatas pada pihak yang menerbitkannya — verifikasi pemanggilan alat pada tugas Anda sendiri terlebih dahulu.

Tetapkan harga model yang benar-benar Anda pilih

Per model, berdasarkan tingkat Standard Google, karena versi perbandingan untuk seluruh keluarga ini tidak benar saat ini:

Tarif Kunavo berasal dari katalog langsung dan tarif Google dari halaman harga yang dibaca pada 21 September 2026; periode pengantar berakhir pada 31 Desember 2026, setelah itu perbandingan Flash kembali berbalik.

Estimasi terperinci, yaitu aritmetika token dan bukan tugas OpenClaw yang diukur atau batas tagihan. Anggap satu minggu pekerjaan asisten yang mengirim 4.000.000 token input yang tidak di-cache dan menerima 150.000 token output, tanpa caching dan tanpa penelusuran. Pada Gemini 3.8 Flash dengan tarif Kunavo, jumlahnya $2,49; aritmetika yang sama pada tarif Flash pengantar Google menjadi $3,56, naik menjadi $7,13 pada tarif 2027. Jalankan volume yang sama pada Gemini 3.6 Flash di Kunavo dan hasilnya $4,99 — lebih tinggi daripada angka pengantar Google, dan itulah alasan id model, bukan nama provider, yang menjadi keputusan.

Jumlah katalog Kunavo adalah batas bawah penagihan, bukan batas maksimum: ketika upstream melaporkan biayanya, tagihan adalah nilai yang lebih besar antara biaya katalog dan biaya upstream dikalikan markup yang berlaku. Biaya cache, grounding penelusuran, dan hosting berada di luar contoh ini, dan top-up minimum adalah $10 dalam kredit prabayar — minimum pendanaan, bukan biaya tugas atau langganan. Lihat detail penagihan dan harga OpenClaw untuk keseluruhan biaya operasional.

Verifikasi dengan satu permintaan, lalu baca kedua buku besar

openclaw config validate
openclaw gateway restart
openclaw models list --provider kunavo
openclaw infer model run --model kunavo/gemini-3-8-flash --prompt "hi" --json

openclaw models list membaca inventaris yang diterbitkan dan openclaw models status menampilkan default serta status autentikasi yang telah ditetapkan; tidak satu pun membuktikan bahwa tugas berbayar berfungsi, dan openclaw models set pada provider yang dikenal menyimpan model yang tidak tercantum di katalog hanya dengan peringatan. openclaw doctor --json --severity-min info juga menampilkan model aktif yang tidak dapat dikonfirmasi oleh katalog lokal (referensi CLI). Satu permintaan di atas adalah bukti pertama yang mengeluarkan biaya.

Lakukan triase berdasarkan kode status. OpenClaw mendokumentasikan tanda model_not_found untuk server lokal yang kompatibel dengan OpenAI, dan tiga field yang disebutnya sama dengan tiga field yang ditetapkan oleh entri custom provider: pastikan baseUrl menyertakan /v1, api adalah "openai-completions" untuk backend /v1/chat/completions, dan models[].id adalah id lokal provider tanpa awalan, dengan awalan provider hanya digunakan saat pemilihan (pemecahan masalah). Terhadap Kunavo, pemeriksaan yang menunjukkan bahwa base URL benar adalah permintaan tanpa autentikasi ke path API nyata: GET https://api.kunavo.com/v1/models menjawab 401 dengan isi authentication_error, yang berarti URL benar dan kunci tidak ada. Host tanpa tambahan dan path /v1 tanpa tambahan bukanlah path API dan menjawab dengan HTML, sehingga klien yang diarahkan ke salah satunya akan gagal sebelum pernah mencapai model (diperiksa pada 21 September 2026). 403 adalah kode yang harus dihentikan dan dibaca: OpenClaw memperingatkan bahwa kode tersebut "dapat berasal dari lapisan keamanan upstream seperti CDN, WAF, aturan manajemen bot, atau reverse proxy", dan bahwa curl minimal yang berhasil tidak menjamin permintaan bergaya SDK sungguhan melewati lapisan yang sama. Lihat model not found dan Gemini API key not working untuk versi yang lebih panjang.

Untuk rute native, mulai dari catatan kunci API Gemini Kunavo dan Google AI Studio; untuk rute gateway, buat kunci di Kunci API dan buka akun Kunavo, lalu ikuti panduan penyedia kustom di API terbaik untuk OpenClaw. Pastikan rute yang sedang digunakan tetap tersedia saat Anda mengujinya.

Rute mana yang unggul ketika

Jika Anda masih memilih penyedia, bukan mengonfigurasinya, Harga API Gemini dan API yang kompatibel dengan OpenAI membahas dua sisi keputusan tersebut.

Pertanyaan umum

Diambil untuk halaman ini pada 21 September 2026: dokumentasi OpenClaw tentang penyedia Google, official-provider-plugins, Gemini-search, web-search, custom-provider (baik konsep maupun referensi gateway), quick-rules, CLI-models, dan troubleshooting; halaman harga Gemini API Google (terakhir diperbarui 16 September 2026), halaman modelnya, halaman grounding Google Search, dan postingan blog pengembangnya pada 19 Mei 2026; entri registri npm untuk openclaw; serta katalog Kunavo sendiri. Pada 1 Oktober 2026, nilai custom-provider api diperiksa ulang terhadap referensi gateway, halaman penyedia Google, serta skema konfigurasi dan transport Interactions OpenClaw dalam sumbernya pada v2026.9.7. Satu-satunya permintaan live yang dibuat untuk halaman ini adalah GET tanpa autentikasi ke /v1/models Kunavo, untuk mencatat 401 yang dijelaskan di atas. Tidak ada bagian di sini yang diuji saat runtime terhadap instalasi OpenClaw, endpoint Kunavo, atau endpoint Google; setiap angka dolar adalah perhitungan ilustratif berdasarkan tarif yang dipublikasikan.