​

Cache prompt

• Cache prompt Anthropic: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• Cache prompt OpenAI: https://developers.openai.com/api/docs/guides/prompt-caching
• Header API dan ID permintaan OpenAI: https://developers.openai.com/api/reference/overview
• ID permintaan dan error Anthropic: https://platform.claude.com/docs/en/api/errors

​

Kontrol utama

​

cacheRetention (default global, model, dan per agen)

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # none | short | long

agents:
  list:
    - id: "alerts"
      params:
        cacheRetention: "none"

1. agents.defaults.params (default global — berlaku untuk semua model)
2. agents.defaults.models["provider/model"].params (override per model)
3. agents.list[].params (id agen yang cocok; override per key)

​

contextPruning.mode: "cache-ttl"

agents:
  defaults:
    contextPruning:
      mode: "cache-ttl"
      ttl: "1h"

​

Heartbeat keep-warm

agents:
  defaults:
    heartbeat:
      every: "55m"

​

Perilaku provider

​

Anthropic (API langsung)

• cacheRetention didukung.
• Dengan profil autentikasi API key Anthropic, OpenClaw mengisi cacheRetention: "short" untuk referensi model Anthropic saat tidak disetel.
• Respons Messages Anthropic native mengekspos cache_read_input_tokens dan cache_creation_input_tokens, sehingga OpenClaw dapat menampilkan cacheRead dan cacheWrite.
• Untuk permintaan Anthropic native, cacheRetention: "short" dipetakan ke cache ephemeral default 5 menit, dan cacheRetention: "long" menaikkan ke TTL 1 jam hanya pada host api.anthropic.com langsung.

​

OpenAI (API langsung)

• Cache prompt bersifat otomatis pada model terbaru yang didukung. OpenClaw tidak perlu menyisipkan penanda cache tingkat blok.
• OpenClaw menggunakan prompt_cache_key untuk menjaga routing cache tetap stabil antar giliran dan menggunakan prompt_cache_retention: "24h" hanya saat cacheRetention: "long" dipilih pada host OpenAI langsung.
• Respons OpenAI mengekspos token prompt yang di-cache melalui usage.prompt_tokens_details.cached_tokens (atau input_tokens_details.cached_tokens pada event Responses API). OpenClaw memetakannya ke cacheRead.
• OpenAI tidak mengekspos penghitung token cache-write terpisah, jadi cacheWrite tetap 0 pada jalur OpenAI meskipun provider sedang menghangatkan cache.
• OpenAI mengembalikan header tracing dan rate-limit yang berguna seperti x-request-id, openai-processing-ms, dan x-ratelimit-*, tetapi akuntansi cache-hit sebaiknya berasal dari payload penggunaan, bukan dari header.
• Dalam praktiknya, OpenAI sering berperilaku seperti cache prefiks awal alih-alih penggunaan ulang riwayat penuh yang bergerak seperti Anthropic. Giliran dengan teks prefiks panjang yang stabil dapat mencapai plateau sekitar 4864 cached token dalam probe live saat ini, sementara transkrip berat tool atau bergaya MCP sering plateau di sekitar 4608 cached token bahkan pada pengulangan yang sama persis.

​

Anthropic Vertex

• Model Anthropic di Vertex AI (anthropic-vertex/*) mendukung cacheRetention dengan cara yang sama seperti Anthropic langsung.
• cacheRetention: "long" dipetakan ke TTL cache prompt 1 jam yang sebenarnya pada endpoint Vertex AI.
• Retensi cache default untuk anthropic-vertex sama dengan default Anthropic langsung.
• Permintaan Vertex dirutekan melalui pembentukan cache yang sadar batas agar penggunaan ulang cache tetap selaras dengan yang benar-benar diterima provider.

​

Amazon Bedrock

• Referensi model Anthropic Claude (amazon-bedrock/*anthropic.claude*) mendukung pass-through cacheRetention eksplisit.
• Model Bedrock non-Anthropic dipaksa menjadi cacheRetention: "none" saat runtime.

​

Model Anthropic OpenRouter

​

Provider lain

​

Google Gemini direct API

• Transport Gemini langsung (api: "google-generative-ai") melaporkan cache hit melalui cachedContentTokenCount upstream; OpenClaw memetakannya ke cacheRead.
• Saat cacheRetention disetel pada model Gemini langsung, OpenClaw secara otomatis membuat, menggunakan kembali, dan menyegarkan resource cachedContents untuk prompt system pada eksekusi Google AI Studio. Ini berarti Anda tidak lagi perlu membuat handle cached-content secara manual sebelumnya.
• Anda tetap dapat meneruskan handle cached-content Gemini yang sudah ada melalui params.cachedContent (atau legacy params.cached_content) pada model yang dikonfigurasi.
• Ini terpisah dari caching prefiks prompt Anthropic/OpenAI. Untuk Gemini, OpenClaw mengelola resource cachedContents native milik provider alih-alih menyisipkan penanda cache ke dalam permintaan.

​

Penggunaan JSON Gemini CLI

• Output JSON Gemini CLI juga dapat menampilkan cache hit melalui stats.cached; OpenClaw memetakannya ke cacheRead.
• Jika CLI menghilangkan nilai stats.input langsung, OpenClaw menurunkan token input dari stats.input_tokens - stats.cached.
• Ini hanya normalisasi penggunaan. Ini tidak berarti OpenClaw membuat penanda cache prompt bergaya Anthropic/OpenAI untuk Gemini CLI.

​

Batas cache system prompt

• File konteks proyek workspace yang stabil diurutkan sebelum HEARTBEAT.md agar perubahan heartbeat tidak merusak prefiks stabil.
• Batas ini diterapkan di seluruh pembentukan cache keluarga Anthropic, keluarga OpenAI, Google, dan transport CLI sehingga semua provider yang didukung mendapatkan manfaat dari stabilitas prefiks yang sama.
• Permintaan Codex Responses dan Anthropic Vertex dirutekan melalui pembentukan cache yang sadar batas agar penggunaan ulang cache tetap selaras dengan yang benar-benar diterima provider.
• Sidik jari system prompt dinormalisasi (whitespace, line ending, konteks yang ditambahkan hook, urutan kemampuan runtime) sehingga prompt yang secara semantik tidak berubah berbagi KV/cache antar giliran.

​

Pelindung stabilitas cache OpenClaw

• Katalog tool MCP bundle diurutkan secara deterministik sebelum registrasi tool, sehingga perubahan urutan listTools() tidak mengubah blok tool dan merusak prefiks cache prompt.
• Sesi legacy dengan blok gambar yang dipersistenkan mempertahankan 3 giliran selesai terbaru tetap utuh; blok gambar lama yang sudah diproses dapat diganti dengan penanda sehingga tindak lanjut yang berat gambar tidak terus mengirim ulang payload lama yang besar dan usang.

​

Pola penyetelan

​

Traffic campuran (default yang direkomendasikan)

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long"
  list:
    - id: "research"
      default: true
      heartbeat:
        every: "55m"
    - id: "alerts"
      params:
        cacheRetention: "none"

​

Baseline yang mengutamakan biaya

• Setel baseline cacheRetention: "short".
• Aktifkan contextPruning.mode: "cache-ttl".
• Jaga heartbeat tetap di bawah TTL Anda hanya untuk agen yang mendapat manfaat dari cache hangat.

​

Diagnostik cache

​

Live regression test

• src/agents/live-cache-regression.live.test.ts
• src/agents/live-cache-regression-baseline.ts

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache

​

Ekspektasi live Anthropic

• Harapkan warmup write eksplisit melalui cacheWrite.
• Harapkan penggunaan ulang hampir seluruh riwayat pada giliran berulang karena kontrol cache Anthropic menggeser breakpoint cache sepanjang percakapan.
• Assertion live saat ini masih menggunakan ambang hit-rate tinggi untuk jalur stabil, tool, dan gambar.

​

Ekspektasi live OpenAI

• Harapkan hanya cacheRead. cacheWrite tetap 0.
• Perlakukan penggunaan ulang cache pada giliran berulang sebagai plateau khusus provider, bukan sebagai penggunaan ulang riwayat bergerak bergaya Anthropic.
• Assertion live saat ini menggunakan pemeriksaan ambang konservatif yang diturunkan dari perilaku live yang diamati pada gpt-5.4-mini:
  • prefiks stabil: cacheRead >= 4608, hit rate >= 0.90
  • transkrip tool: cacheRead >= 4096, hit rate >= 0.85
  • transkrip gambar: cacheRead >= 3840, hit rate >= 0.82
  • transkrip bergaya MCP: cacheRead >= 4096, hit rate >= 0.85

• prefiks stabil: cacheRead=4864, hit rate 0.966
• transkrip tool: cacheRead=4608, hit rate 0.896
• transkrip gambar: cacheRead=4864, hit rate 0.954
• transkrip bergaya MCP: cacheRead=4608, hit rate 0.891

• Anthropic mengekspos breakpoint cache eksplisit dan penggunaan ulang riwayat percakapan yang bergerak.
• Cache prompt OpenAI masih sensitif terhadap prefiks yang persis sama, tetapi prefiks yang dapat digunakan ulang secara efektif dalam traffic Responses live dapat plateau lebih awal daripada prompt penuh.
• Karena itu, membandingkan Anthropic dan OpenAI dengan satu ambang persentase lintas provider akan menciptakan regresi palsu.

​

Konfigurasi diagnostics.cacheTrace

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # optional
    includeMessages: false # default true
    includePrompt: false # default true
    includeSystem: false # default true

• filePath: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl
• includeMessages: true
• includePrompt: true
• includeSystem: true

​

Toggle env (debugging sekali pakai)

• OPENCLAW_CACHE_TRACE=1 mengaktifkan cache tracing.
• OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl mengganti path output.
• OPENCLAW_CACHE_TRACE_MESSAGES=0|1 mengaktifkan/nonaktifkan perekaman payload pesan penuh.
• OPENCLAW_CACHE_TRACE_PROMPT=0|1 mengaktifkan/nonaktifkan perekaman teks prompt.
• OPENCLAW_CACHE_TRACE_SYSTEM=0|1 mengaktifkan/nonaktifkan perekaman system prompt.

​

Yang perlu diperiksa

• Event cache trace berbentuk JSONL dan mencakup snapshot bertahap seperti session:loaded, prompt:before, stream:context, dan session:after.
• Dampak token cache per giliran terlihat pada permukaan penggunaan normal melalui cacheRead dan cacheWrite (misalnya /usage full dan ringkasan penggunaan sesi).
• Untuk Anthropic, harapkan cacheRead dan cacheWrite saat caching aktif.
• Untuk OpenAI, harapkan cacheRead pada cache hit dan cacheWrite tetap 0; OpenAI tidak memublikasikan field token cache-write terpisah.
• Jika Anda memerlukan request tracing, catat ID permintaan dan header rate-limit secara terpisah dari metrik cache. Output cache-trace OpenClaw saat ini berfokus pada bentuk prompt/sesi dan penggunaan token yang dinormalisasi, bukan pada header respons provider mentah.

​

Pemecahan masalah cepat

• cacheWrite tinggi pada sebagian besar giliran: periksa input system prompt yang volatil dan verifikasi bahwa model/provider mendukung setelan cache Anda.
• cacheWrite tinggi pada Anthropic: sering berarti breakpoint cache berada pada konten yang berubah di setiap permintaan.
• cacheRead OpenAI rendah: verifikasi bahwa prefiks stabil berada di bagian depan, prefiks yang diulang setidaknya 1024 token, dan prompt_cache_key yang sama digunakan kembali untuk giliran yang seharusnya berbagi cache.
• Tidak ada efek dari cacheRetention: konfirmasi key model cocok dengan agents.defaults.models["provider/model"].
• Permintaan Bedrock Nova/Mistral dengan setelan cache: pemaksaan runtime ke none memang diharapkan.

• Anthropic
• Penggunaan Token dan Biaya
• Pemangkasan Sesi
• Referensi Konfigurasi Gateway