OpenClaw

~/.openclaw/openclaw.json içindeki tek bir models.providers girdisi — baseUrl https://api.kunavo.com, api "anthropic-messages" — sürekli çalışan bir OpenClaw ajanını Claude'a bağlar; özel bir Anthropic uç noktası, bu ayar yapılana kadar hiçbir önbellek işaretçisi almadığı için cacheRetention da bu girdinin yanına eklenir.

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

Adım adım

1. /app/keys adresinde bir anahtar oluşturup kopyalayın — anahtar yalnızca bir kez gösterilir.
2. Anahtarı Gateway'e tanıtın: KUNAVO_API_KEY=sk-kn-... değerini ~/.openclaw/.env dosyasına ekleyin veya Gateway'in başlatıldığı ortamda dışa aktarın. Bloktaki ${KUNAVO_API_KEY} yükleme sırasında buradan alınan değerle değiştirilir.
3. Mevcut sağlayıcılarınızı, ajanlarınızı ve kanallarınızı koruyarak bloğu ~/.openclaw/openclaw.json dosyasıyla birleştirin. Dosya JSON5 biçimindedir; bu nedenle yorumlar kalabilir.
4. openclaw config validate komutunu çalıştırın. Dosyada tanımadığı bir ayar varsa OpenClaw başlatmayı reddeder; bu nedenle bir yazım hatasını burada bulmak, bir sonraki yeniden başlatmada bulmaktan iyidir.
5. openclaw models list --provider kunavo komutunu çalıştırın ve her iki kimliğin de listelendiğini doğrulayın. Çalışan bir Gateway değişikliği henüz almamışsa openclaw gateway restart komutunu çalıştırın.
6. /new komutuyla yeni bir oturum açın — mevcut oturum kullandığı modeli korur — iki mesaj gönderin, ardından /usage tokens çıktısını inceleyin: ikinci turda cacheRead görünmelidir.

OpenClaw'ın özel sağlayıcılar başvuru belgesi ile 5 Ekim 2026 tarihinde kontrol edilmiştir. Üçüncü taraf ayarları değişebilir; buradaki alan adı gördüğünüzle artık eşleşmiyorsa yetkili kaynak bu sayfa değil, ilgili sayfadır.

İstemcide hata ayıklamadan önce doğrulayın

Tek bir istek, hatanın uç noktadan mı, anahtardan mı yoksa yapılandırma dosyasından mı kaynaklandığını kesinleştirir. Bu JSON döndürürse aynı temel URL ve anahtar OpenClaw içinde çalışır.

# 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"}]}'

Alana hangi model kimliği yazılmalı

Her metin modeline model kimliğiyle erişilebilir — güncel liste GET /v1/models, fiyatları içeren katalog ise modeller sayfasında. Ücretler 1 milyon token başına USD cinsindendir; giriş / çıkış.

OpenAI uyumlu bağlantı biçimi

Aynı anahtar, diğer tüm model ailelerine de /v1/chat/completions üzerinden ulaşır. İki bağlantı biçimini ayrı tutmak için bunu ikinci bir sağlayıcı girdisi olarak kaydedin ve modellerine kunavo-openai/<id> biçiminde başvurun:

// ~/.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

Yukarıdaki bloktan üç farkı vardır. OpenClaw'ın kendi özel sağlayıcı örneklerinde kullanılan biçime uygun olarak base URL'de /v1 korunur. api, openai-completions değeridir; OpenClaw, özel bir sağlayıcıda baseUrl bulunup api bulunmadığında da bu değeri varsayar. Ayrıca maxTokens uygulamada isteğe bağlı olmaktan çıkar: bir modelin çıktı sınırı bilinmiyorsa OpenClaw bu bağlantı biçiminde hiç sınır göndermez ve Kunavo Claude yanıtını 4.096 tokena ulaştığında sonlandırır.

Claude kimlikleri bu bağlantı biçiminde de çalışır ve her şey için tek bir girdi istiyorsanız kullanmanız gereken biçim budur. Claude için iki şey değişir: chat completions üzerinden düşünme düzeyleri iletilmez ve önbellek kesme noktalarını OpenClaw değil Kunavo yerleştirir.

Her bağlantı biçiminde istem önbelleğe alma

Anthropic bağlantı biçiminde önbellek kesme noktalarını OpenClaw kendisi yerleştirir; ancak bunu özel bir uç noktada yalnızca cacheRetention ayarlanmışsa yapar. istem önbelleğe alma başvuru belgesi bu konuda nettir: short varsayılanı yalnızca anthropic ve anthropic-vertex sağlayıcıları için tanımlıdır; Anthropic ailesindeki diğer tüm yönlendirmelerde açık bir değer gerekir. Kunavo'nun /v1/messages uç noktası gövdeyi gönderildiği gibi iletir ve kesme noktası eklemez; dolayısıyla bu satırlar eklenmemiş bir yapılandırma hiçbir şeyi önbelleğe almaz.

short, beş dakikalık girdiyi; long ise bir saatlik girdiyi ister. Kunavo her iki işaretçiyi de iletir ve yazma işlemini aynı ücret üzerinden faturalandırır. Bir saatlik girdinin sonraki kalp atışı geldiğinde hâlâ kullanılabilir olup olmadığını, aralık planınızı buna göre belirlemeden önce kendi kullanımınızda doğrulayın: cacheRead bildiren bir turda önbellek korunmuştur; yeniden cacheWrite bildiren bir turda korunmamıştır. Her iki sayacı da /usage tokens ve /status gösterir.

OpenAI uyumlu bağlantı biçiminde durum tersidir. OpenClaw bir proxy uç noktasına önbellek ipuçları göndermez; istem yeterince uzunsa Claude modelleri için kesme noktalarını Kunavo kendisi, sistem istemine, araç tanımlarına ve konuşmanın sonuna yerleştirir. Yapılandırılması gereken bir ayar yoktur; GPT modelleri ise sağlayıcıları tarafından örtük olarak önbelleğe alınır.

Kesme noktalarını hangi taraf yerleştirirse yerleştirsin, fatura aynıdır. Claude Sonnet 5 için önbellekten okuma, 1 milyon token başına $0.14; yeni girdi için ücret ise $1.40 tutarındadır. Önbelleğe yazma ücreti $1.75 tutarındadır: Claude'un girdiye uyguladığı yazma farkı. Girdi bir saatlik ömür istese de aynı ücret alınır. Her girdi beş dakika sürer ve her okuma süresini yeniler; bu nedenle bir ajanın ödeyeceği tutar modelden çok, bir sonraki isteğinin bu süre içinde gelip gelmemesine bağlıdır. Her modelin önbellek ücretleri istem önbelleğe alma sayfasında yer alır.

OpenClaw aynı hesaplamayı yerel olarak da gösterebilir. /usage cost özeti ve /status içindeki maliyet satırı, her model satırında bir cost nesnesi gerektirir; bu nesne yoksa ikisi de sıfır gösterirken Kunavo her zamanki gibi ücret alır. Bu satırlar canlı katalogdan oluşturulur:

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

Sürekli çalışan bir ajanın günlük maliyeti

OpenClaw aracısı, kimse onunla konuşmadığında da kalp atışı nedeniyle ücret oluşturur: bu, varsayılan olarak her 30 dakikada bir çalışan zamanlanmış bir aracı turudur; bu da günde 48 eder. Aksi belirtilmedikçe ana oturumda çalışır ve konuşmayı yeniden gönderir. OpenClaw'ın başvuru belgesine göre böyle bir çalıştırma yaklaşık 100.000 token kullanır; ayrı bir oturumda çalıştırıldığında ise birkaç bin token kullanır. Otuz dakika, beş dakikalık önbellek süresinden uzun olduğundan her çalıştırmada istemin tamamı yeniden ücretlendirilir: girdi tarifesi üzerinden veya bir kesme noktası yerleştirildiğinde daha yüksek olan yazma tarifesi üzerinden. Tabloda, ayrı oturumdaki çalıştırma için 5.000 token varsayılarak bir boş günün maliyeti girdi tarifesi üzerinden gösterilmiştir:

Aşağıdaki blok, tablonun düşük maliyetli seçeneğidir: Haiku üzerinde, ayrı bir oturumda, çalışma alanının başlangıç dosyaları olmadan ve yalnızca uyanık olunan saatlerde çalışan kalp atışları. İçindeki her ayar OpenClaw'ın kalp atışı başvuru belgesinden alınmıştır. every aralığını uzatmak maliyeti azaltmanın diğer yoludur; "0m" ise yinelenen çalıştırmayı kapatır.

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

Aracının gerçekten çalıştığı saatler faturanın diğer yarısını oluşturur; bu noktada belirleyici olan önbellektir. Her biri 100.000 tokenlık bağlamı yeniden gönderen, buna 2.000 yeni token ekleyen ve 800 çıktı tokenı döndüren 100 ardışık isteği ele alalım. Claude Sonnet 5 için bağlam önbellekten okunurken maliyet yaklaşık $2.31, her istek bağlamı yeni girdi olarak ücretlendirdiğinde ise yaklaşık $14.84 olur. İş aynı, model aynı: fark, kesme noktalarının bulunup bulunmamasına ve isteklerin arasında beş dakikadan az süre geçmesine bağlıdır.

Ölçeği tahminle değil, ölçümle görelim: sürekli çalışan bir aracı bulunan Kunavo hesaplarında, etkin bir günün medyan maliyeti $12.67, 90. yüzdelik dilimdeki bir günün maliyeti ise yaklaşık $163 düzeyindedir. Bunlar, her gün geçerli olan ücretler üzerinden 5 Ekim 2026 tarihine kadar faturalandırılan tutarlardır. Grup küçük olduğundan, bunu aracınız için bir tahmin olarak değil, aralığın genişliğini gösteren bir ölçüm olarak değerlendirin.

Bakiye bittiğinde

Kunavo ön ödemelidir: her çağrı cüzdandaki bakiyeden ödenir ve siz uyurken çalışan bir aracı da siz uyurken bu bakiyeyi tüketir. Cüzdanın karşılayamayacağı bir istek, her iki aktarım biçiminde de HTTP 402 ve insufficient_balance koduyla reddedilir; bu istek için ücret alınmaz. Ret, cüzdan bakiyesi sıfıra inmeden gerçekleşir: her istek için önce en yüksek olası maliyet, yani istem ve üretmesine izin verilen en uzun yanıt rezerve edilir. Bu nedenle aracının istediği çıktı sınırı ne kadar yüksekse çağrıları da o kadar erken reddedilmeye başlar. Hata, ne kadar eksik bakiye olduğunu balance_usd ve needed_usd alanlarında belirtir.

OpenClaw, 402 yanıtının ne anlama geldiğini mesajına göre belirler. OpenClaw 2026.9.8 kurallarına göre cüzdan yetersizliği reddi bir faturalandırma hatasıdır; yedek modele geçiş başvuru belgesi de sonrasında ne olacağını açıklar: kimlik bilgisi on dakika devre dışı bırakılır, çalıştırma agents.defaults.model.fallbacks içindeki sonraki modele geçer ve yeniden bakiye yüklemek bu süreyi sıfırlamaz. Bu nedenle bakiye yükledikten sonra aracı, süre dolana kadar kunavo/… için devre dışı kalabilir. Bir anahtarın aylık limiti nedeniyle gelen ret ise farklı değerlendirilir. Mesajda sıfırlanan bir limit belirtilir ve aynı kurallar bunu hız sınırı olarak ele alır: OpenClaw yeniden dener, ardından kimlik bilgisini önce 30 saniyeliğine, en fazla da beş dakikalığına beklemeye alır. openclaw models status, devre dışı bırakılmış kimlik bilgisini ve ne zaman yeniden kullanılabileceğini listeler.

Denetimsiz çalışan bir ajanın bu duruma düşmesini iki ayar önler; bu ayarlar farklı işlevler görür:

• Otomatik yükleme, Faturalandırma bölümünde. Kartı bir kez kaydedin ve üç değer belirleyin: bakiye hangi tutarın altına düştüğünde yükleme yapılacağı, her seferinde eklenecek tutar ve aylık üst sınır. Cüzdan, bakiyeyi eşik tutarın altına düşüren bir çağrıdan saniyeler sonra yenilenir. Cüzdan bakiyesi hâlâ yetersizken gelen bir istek, ücretlendirmenin tamamlanmasını bekler ve ardından reddedilmek yerine işleme alınır. Ücret alınamadığında (kartın reddedilmesi veya aylık üst sınıra ulaşılması) ya da tek bir isteğin ayırdığı tutar, yükleme sonrasında cüzdandaki bakiyeyi aştığında 402 yine döner. Otomatik ücretlendirme için kart veya Link gerekir; Alipay, WeChat Pay, Pix ve diğer yerel ödeme yöntemlerinden otomatik olarak ücret alınamaz.
• API anahtarına aylık bir harcama sınırı, API anahtarları bölümünde. Aracıya kendi API anahtarını verin ve bu anahtarın bir takvim ayında harcayabileceği en yüksek tutarı belirleyin. Bu tutar aşıldığında, diğer anahtarlarınız çalışmaya devam ederken aracının çağrıları 402 ile reddedilir ve ücret alınmaz. Kontrolden çıkan bir döngüye karşı gereken üst sınır budur; cüzdan bunu sağlayamaz, çünkü tüm anahtarlar aynı cüzdandan harcama yapar.

Yükleme eşiğini tek bir isteğin rezerve ettiği tutarın üstünde belirleyin; yüklenecek tutarı da asgari miktara göre değil, ajanınızın bir günlük kullanımına göre ayarlayın: en küçük yükleme tutarı $10, yukarıdaki sürekli çalışan ajanların medyan günlük maliyeti ise $12.67. Otomatik bakiye yüklemenin sınırları faturalandırma sayfasında, hata yanıtının tamamı ise hatalar sayfasında açıklanmıştır.

İlgili kılavuzlar

• OpenClaw için en iyi API — her görev türü için sağlayıcı ve model seçimi.
• OpenClaw fiyatlandırması — yazılım, barındırma, modeller ve araçlar dahil toplam işletim maliyeti.
• Birden fazla ajan ve modelle OpenClaw — her ajanı kendi modeline yönlendirme ve faturadaki maliyetleri ilgili yönlendirmelerle ilişkilendirme.
• Hermes ve OpenClaw karşılaştırması — diğer ajan için aynı kurulum, Hermes Agent sayfasında.