OpenClaw

Satu entri models.providers di ~/.openclaw/openclaw.json — baseUrl https://api.kunavo.com, api "anthropic-messages" — menghubungkan agen OpenClaw yang selalu aktif ke Claude; cacheRetention ditetapkan bersamanya, karena endpoint Anthropic khusus tidak menerima penanda cache sebelum pengaturan itu diisi.

// ~/.openclaw/openclaw.json — merge into the file you already have
{
  models: {
    mode: "merge",
    providers: {
      kunavo: {
        baseUrl: "https://api.kunavo.com",   // origin — no /v1 on this wire
        apiKey: "${KUNAVO_API_KEY}",         // from the environment or ~/.openclaw/.env
        api: "anthropic-messages",
        models: [
          {
            id: "claude-sonnet-5",
            name: "Claude Sonnet 5",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1000000,
            contextTokens: 200000,           // optional: compact here, not at 1M
            maxTokens: 32000,
          },
          {
            id: "claude-haiku-4-5",
            name: "Claude Haiku 4.5",
            input: ["text", "image"],
            contextWindow: 200000,
            maxTokens: 16000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "kunavo/claude-sonnet-5" },
      models: {
        // Required for caching: a custom Anthropic endpoint gets no cache
        // markers from OpenClaw until cacheRetention is set explicitly.
        "kunavo/claude-sonnet-5": { params: { cacheRetention: "short" } },
        "kunavo/claude-haiku-4-5": { params: { cacheRetention: "short" } },
      },
    },
  },
}

Langkah demi langkah

1. Buat key di /app/keys dan salin — key hanya ditampilkan sekali.
2. Berikan kunci kepada Gateway: tambahkan KUNAVO_API_KEY=sk-kn-... ke ~/.openclaw/.env, atau ekspor kunci tersebut ke lingkungan tempat Gateway dijalankan. Saat konfigurasi dimuat, ${KUNAVO_API_KEY} dalam blok akan diganti dengan nilainya.
3. Gabungkan blok tersebut ke ~/.openclaw/openclaw.json, dengan mempertahankan penyedia, agen, dan saluran yang sudah ada. File ini menggunakan JSON5, jadi komentar dapat tetap disertakan.
4. Jalankan openclaw config validate. OpenClaw menolak untuk memulai jika file berisi pengaturan yang tidak dikenalnya, jadi lebih baik menemukan salah ketik di sini daripada saat memulai ulang berikutnya.
5. Jalankan openclaw models list --provider kunavo dan pastikan kedua ID tercantum. Jika Gateway yang sedang berjalan belum menerapkan perubahan, jalankan openclaw gateway restart.
6. Buka sesi baru dengan /new — sesi yang sudah ada akan tetap menggunakan model sebelumnya — kirim dua pesan, lalu lihat /usage tokens: giliran kedua seharusnya menampilkan cacheRead.

Diperiksa terhadap Referensi penyedia khusus OpenClaw pada 5 Oktober 2026. Pengaturan pihak ketiga dapat berubah; jika nama bidang di sini tidak lagi sama dengan yang Anda lihat, halaman tersebut adalah acuan, bukan halaman ini.

Verifikasi sebelum men-debug klien

Satu permintaan menentukan apakah masalahnya ada pada endpoint, kunci, atau berkas konfigurasi. Jika ini mengembalikan JSON, base URL dan kunci yang sama berfungsi di OpenClaw.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

ID model yang harus dimasukkan ke bidang

Setiap model teks dapat diakses melalui ID model — daftar terkininya ada di GET /v1/models, dan katalog beserta harga ada di halaman model. Tarif dalam USD per 1 juta token, input / output.

Protokol yang kompatibel dengan OpenAI

Kunci yang sama dapat digunakan untuk semua keluarga model lainnya melalui /v1/chat/completions. Daftarkan sebagai entri penyedia kedua agar kedua protokol tetap terpisah, lalu rujuk modelnya sebagai kunavo-openai/<id>:

// ~/.openclaw/openclaw.json — a second entry, beside "kunavo"
{
  models: {
    providers: {
      "kunavo-openai": {
        baseUrl: "https://api.kunavo.com/v1",   // this wire keeps /v1
        apiKey: "${KUNAVO_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gpt-6-sol",
            name: "GPT-6 Sol",
            reasoning: true,
            input: ["text"],
            contextWindow: 1050000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

// then: /model kunavo-openai/gpt-6-sol

Ada tiga perbedaan dari blok di bagian atas. Base URL tetap menyertakan /v1, sesuai format yang digunakan dalam contoh penyedia khusus OpenClaw. api bernilai openai-completions — nilai yang juga diasumsikan OpenClaw ketika penyedia khusus memiliki baseUrl tetapi tidak memiliki api. Dan maxTokens tidak lagi bisa diabaikan dalam praktiknya: ketika batas output model tidak diketahui, OpenClaw tidak mengirim batas apa pun pada protokol ini, lalu Kunavo menghentikan balasan Claude setelah 4.096 token.

ID Claude juga dapat digunakan di sini, dan protokol ini cocok jika Anda menginginkan satu entri untuk semuanya. Ada dua hal yang berbeda untuk Claude: tingkat penalaran tidak diteruskan pada chat completions, dan titik pemisah cache ditempatkan oleh Kunavo, bukan OpenClaw.

Caching prompt pada tiap protokol

Pada protokol Anthropic, OpenClaw sendiri menempatkan titik pemisah cache, tetapi untuk endpoint khusus, hal itu dilakukan hanya jika cacheRetention ditetapkan. Referensi caching prompt OpenClaw menjelaskan hal ini secara spesifik: nilai default short disiapkan hanya untuk penyedia anthropic dan anthropic-vertex, sedangkan semua rute lain dalam keluarga Anthropic memerlukan nilai yang ditetapkan secara eksplisit. /v1/messages Kunavo meneruskan isi permintaan apa adanya tanpa menambahkan titik pemisah, jadi konfigurasi tanpa baris tersebut tidak menyimpan apa pun ke cache.

short meminta entri lima menit, sedangkan long meminta entri satu jam. Kunavo meneruskan penanda mana pun yang digunakan dan menagihkan biaya penulisan dengan tarif yang sama. Sebelum menjadikan entri satu jam sebagai dasar penjadwalan heartbeat, pastikan dengan memeriksa penggunaan Anda sendiri apakah entri itu masih tersedia saat heartbeat berikutnya tiba: giliran yang menampilkan cacheRead berarti cache masih tersimpan, sedangkan yang kembali menampilkan cacheWrite berarti cache tidak lagi tersimpan. /usage tokens dan /status menampilkan kedua penghitung tersebut.

Pada protokol yang kompatibel dengan OpenAI, prosesnya berkebalikan. OpenClaw tidak mengirim petunjuk cache ke endpoint proxy, dan Kunavo sendiri menempatkan titik pemisah untuk model Claude — pada prompt sistem, definisi alat, dan akhir percakapan — setelah prompt cukup panjang untuk di-cache. Tidak ada yang perlu dikonfigurasi, dan model GPT di-cache secara implisit oleh vendornya.

Pihak mana pun yang menempatkan titik pemisah, tagihannya tetap sama. Pada Claude Sonnet 5, pembacaan cache dikenai biaya $0.14 per 1M token, dibandingkan $1.40 untuk input baru, dan penulisan cache dikenai biaya $1.75 — premi penulisan yang dikenakan Claude di atas input, dengan tarif yang sama saat entri meminta masa berlaku satu jam. Entri berlaku selama lima menit dan setiap pembacaan memperbarui masa berlakunya, jadi biaya yang dibayar agen lebih ditentukan oleh apakah permintaan berikutnya tiba dalam jangka waktu itu daripada oleh modelnya. Tarif cache setiap model tercantum di halaman caching prompt.

OpenClaw dapat menampilkan perhitungan yang sama secara lokal. Ringkasan /usage cost dan baris biaya di /status memerlukan objek cost pada setiap baris model; tanpanya, nilainya akan menjadi nol meskipun Kunavo tetap menagih seperti biasa. Baris ini dihasilkan dari katalog aktif:

// merge into the rows of models.providers.kunavo.models — USD per 1M tokens
{ id: "claude-sonnet-5", cost: { input: 1.4, output: 7, cacheRead: 0.14, cacheWrite: 1.75 } },
{ id: "claude-haiku-4-5", cost: { input: 0.7, output: 3.5, cacheRead: 0.07, cacheWrite: 0.875 } },
{ id: "claude-opus-5-5", cost: { input: 2.8, output: 14, cacheRead: 0.14, cacheWrite: 3.5 } },
{ id: "claude-fable-5", cost: { input: 7, output: 35, cacheRead: 0.7, cacheWrite: 8.75 } },

Biaya harian agen yang selalu aktif

Agen OpenClaw tetap menimbulkan biaya saat tidak ada yang berinteraksi dengannya karena heartbeat: giliran agen terjadwal yang secara default berjalan setiap 30 menit, yaitu 48 per hari. Jika tidak ditentukan lain, heartbeat berjalan di sesi utama dan mengirim ulang percakapan—dokumentasi referensi OpenClaw memperkirakan proses seperti ini menggunakan sekitar 100.000 token, dan beberapa ribu token jika dijalankan secara terisolasi. Jarak 30 menit melebihi jendela cache lima menit, sehingga setiap proses menagih ulang seluruh prompt: dengan tarif input, atau tarif penulisan yang lebih tinggi jika breakpoint ditempatkan. Tabel ini menghitung biaya satu hari tanpa aktivitas dengan tarif input, menggunakan 5.000 token untuk proses terisolasi:

Bagian di bawah ini menunjukkan opsi berbiaya rendah dalam tabel tersebut: heartbeat di Haiku, dalam sesi terisolasi, tanpa berkas bootstrap ruang kerja, dan hanya selama jam aktif. Semua pengaturan di dalamnya berasal dari referensi heartbeat OpenClaw. Interval every yang lebih panjang adalah opsi pengaturan lainnya, sedangkan "0m" menonaktifkan proses berulang.

// ~/.openclaw/openclaw.json — what decides the cost of an idle day
{
  agents: {
    defaults: {
      utilityModel: "kunavo/claude-haiku-4-5",   // titles and other short internal tasks
      heartbeat: {
        every: "30m",                            // the default with an API key
        model: "kunavo/claude-haiku-4-5",        // wake-ups on the cheapest tier
        isolatedSession: true,                   // a fresh session, not the whole conversation
        lightContext: true,                      // skip the workspace bootstrap files
        activeHours: { start: "08:00", end: "24:00" },
      },
    },
  },
}

Jam-jam ketika agen benar-benar bekerja adalah separuh tagihan lainnya, dan di sinilah cache menentukan biayanya. Ambil 100 permintaan berurutan, masing-masing mengirim ulang konteks 100.000 token dengan tambahan 2.000 token baru, lalu menghasilkan 800 token keluaran. Dengan Claude Sonnet 5, biayanya sekitar $2.31 saat konteks dibaca dari cache, dan sekitar $14.84 ketika setiap permintaan menagihnya sebagai input baru. Pekerjaannya sama, modelnya sama: perbedaannya terletak pada ada tidaknya breakpoint dan jarak antarpermintaan yang kurang dari lima menit.

Sebagai gambaran skala, berdasarkan pengukuran, bukan asumsi: di antara akun Kunavo yang menjalankan agen selalu aktif, biaya hari aktif median adalah $12.67 dan biaya hari persentil ke-90 sekitar $163. Jumlah tersebut ditagihkan hingga 5 Oktober 2026, dengan tarif yang berlaku pada masing-masing hari. Jumlah sampelnya kecil, jadi pahami ini sebagai rentang, bukan prakiraan untuk agen Anda.

Saat saldo habis

Kunavo menggunakan sistem prabayar: setiap panggilan dibayar dari dompet, dan agen yang bekerja saat Anda tidur akan mengurasnya selama Anda tidur. Permintaan yang tidak dapat ditanggung oleh saldo dompet ditolak dengan HTTP 402 dan kode insufficient_balance, pada kedua protokol, dan tidak dikenai biaya. Penolakan terjadi sebelum saldo dompet mencapai nol: setiap permintaan terlebih dahulu mencadangkan biaya maksimum, yaitu prompt ditambah balasan terbesar yang diizinkan untuk dihasilkan. Karena itu, semakin besar batas keluaran yang diminta agen, semakin cepat panggilannya mulai ditolak. Error tersebut menyebutkan kekurangan saldo dalam balance_usd dan needed_usd.

OpenClaw menentukan arti 402 berdasarkan pesannya. Menurut aturan dalam OpenClaw 2026.9.8, penolakan karena saldo dompet termasuk kegagalan penagihan, dan referensi failover-nya menjelaskan tindakan selanjutnya: kredensial dinonaktifkan selama sepuluh menit, eksekusi beralih ke model berikutnya dalam agents.defaults.model.fallbacks, dan pengisian ulang saldo tidak menghapus masa penonaktifan—jadi setelah saldo diisi ulang, agen dapat tetap berhenti menggunakan kunavo/… sampai masa tersebut berakhir. Penolakan karena batas bulanan pada sebuah kunci ditangani secara berbeda. Pesannya menyebut batas yang akan direset, yang menurut aturan yang sama dianggap sebagai pembatasan laju: OpenClaw mencoba kembali, lalu mendinginkan kredensial selama 30 detik pada awalnya, hingga maksimal lima menit. openclaw models status menampilkan kredensial yang dinonaktifkan dan waktu pemulihannya.

Ada dua pengaturan yang mencegah agen tanpa pengawasan mengalami kondisi itu, dan fungsinya berbeda:

• Isi ulang otomatis, di bawah Tagihan. Simpan kartu sekali dan atur tiga angka: ambang saldo yang memicu isi ulang ketika saldo turun di bawahnya, jumlah yang ditambahkan setiap kali, dan batas bulanan. Setelah panggilan API membuat saldo turun di bawah ambang tersebut, saldo dompet akan terisi kembali dalam hitungan detik. Permintaan yang masuk saat saldo dompet masih kurang akan menunggu hingga tagihan tersebut diproses, lalu dilayani alih-alih ditolak. 402 tetap dikembalikan jika tagihan tidak dapat diproses — kartu ditolak atau batas bulanan tercapai — maupun jika satu permintaan mencadangkan jumlah yang melebihi saldo dompet setelah isi ulang. Fitur ini memerlukan kartu atau Link — Alipay, WeChat Pay, Pix, dan metode pembayaran lokal lainnya tidak dapat ditagih secara otomatis.
• Batas bulanan untuk kunci, di bawah Kunci API. Berikan kunci tersendiri kepada agen dan tetapkan jumlah maksimum yang dapat dibelanjakan oleh kunci tersebut dalam satu bulan kalender. Setelah melewati jumlah itu, panggilannya akan ditolak dengan 402 dan tidak ada biaya yang dikenakan, sementara kunci Anda yang lain tetap berfungsi. Batas inilah yang diperlukan untuk menahan loop yang berjalan tanpa kendali, dan tidak dapat disediakan oleh dompet karena semua kunci menggunakan dompet yang sama.

Tetapkan ambang isi ulang di atas jumlah yang dicadangkan untuk satu permintaan, dan tentukan jumlah isi ulang berdasarkan kebutuhan agen selama sehari, bukan jumlah minimum: isi ulang terkecil adalah $10, sedangkan biaya harian median agen selalu aktif di atas adalah $12.67. Batas isi ulang otomatis dijelaskan di halaman penagihan, dan seluruh isi badan kesalahan tercantum di halaman kesalahan.

Panduan terkait

• API terbaik untuk OpenClaw — memilih penyedia dan model untuk setiap jenis tugas.
• Harga OpenClaw — keseluruhan biaya operasional: perangkat lunak, hosting, model, dan alat.
• OpenClaw dengan beberapa agen dan model — mengarahkan setiap agen ke modelnya sendiri dan mengatribusikan biaya berdasarkan rute.
• Hermes vs OpenClaw — dan konfigurasi yang sama untuk agen lainnya, di halaman Hermes Agent.