​

Failover model

1. Rotasi profil auth di dalam provider saat ini.
2. Fallback model ke model berikutnya dalam agents.defaults.model.fallbacks.

​

Alur runtime

1. Model sesi yang saat ini dipilih.
2. agents.defaults.model.fallbacks yang dikonfigurasi secara berurutan.
3. Model utama yang dikonfigurasi di akhir ketika run dimulai dari override.

1. Selesaikan model sesi aktif dan preferensi profil auth.
2. Bangun rantai kandidat model.
3. Coba provider saat ini dengan aturan rotasi/cooldown profil auth.
4. Jika provider itu habis dengan error yang layak untuk failover, pindah ke kandidat model berikutnya.
5. Persistenkan override fallback yang dipilih sebelum percobaan ulang dimulai agar pembaca sesi lain melihat provider/model yang sama yang akan digunakan runner.
6. Jika kandidat fallback gagal, rollback hanya field override sesi milik fallback ketika field tersebut masih cocok dengan kandidat gagal itu.
7. Jika setiap kandidat gagal, lempar FallbackSummaryError dengan detail per percobaan dan waktu kedaluwarsa cooldown tercepat ketika diketahui.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Penyimpanan auth (kunci + OAuth)

• Secret disimpan di ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (lama: ~/.openclaw/agent/auth-profiles.json).
• State perutean auth runtime disimpan di ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• Konfigurasi auth.profiles / auth.order hanya untuk metadata + perutean (tanpa secret).
• File OAuth lama khusus impor: ~/.openclaw/credentials/oauth.json (diimpor ke auth-profiles.json saat pertama kali digunakan).

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl untuk beberapa provider)

​

ID profil

• Default: provider:default saat tidak ada email yang tersedia.
• OAuth dengan email: provider:<email> (misalnya google-antigravity:user@gmail.com).

​

Urutan rotasi

1. Konfigurasi eksplisit: auth.order[provider] (jika disetel).
2. Profil yang dikonfigurasi: auth.profiles yang difilter berdasarkan provider.
3. Profil yang tersimpan: entri dalam auth-profiles.json untuk provider tersebut.

• Kunci utama: tipe profil (OAuth sebelum API key).
• Kunci sekunder: usageStats.lastUsed (yang paling lama digunakan lebih dulu, dalam setiap tipe).
• Profil cooldown/dinonaktifkan dipindahkan ke akhir, diurutkan menurut waktu kedaluwarsa tercepat.

​

Keketatan sesi (ramah cache)

• sesi di-reset (/new / /reset)
• compaction selesai (jumlah compaction bertambah)
• profil berada dalam cooldown/dinonaktifkan

​

Mengapa OAuth bisa “terlihat hilang”

• Sematkan dengan auth.order[provider] = ["provider:profileId"], atau
• Gunakan override per sesi melalui /model … dengan override profil (jika didukung oleh permukaan UI/chat Anda).

​

Cooldown

• OpenClaw mencatat cooldownModel untuk kegagalan batas laju ketika id model yang gagal diketahui.
• Model saudara pada provider yang sama masih dapat dicoba ketika cooldown dicakup ke model yang berbeda.
• Jendela billing/dinonaktifkan tetap memblokir seluruh profil di semua model.

• 1 menit
• 5 menit
• 25 menit
• 1 jam (batas maksimum)

{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

​

Penonaktifan billing

{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}

• Backoff billing dimulai pada 5 jam, berlipat ganda per kegagalan billing, dan dibatasi pada 24 jam.
• Penghitung backoff di-reset jika profil tidak gagal selama 24 jam (dapat dikonfigurasi).
• Percobaan ulang overloaded mengizinkan 1 rotasi profil provider yang sama sebelum fallback model.
• Percobaan ulang overloaded menggunakan backoff 0 md secara default.

​

Fallback model

​

Aturan rantai kandidat

• Model yang diminta selalu pertama.
• Fallback eksplisit yang dikonfigurasi dihapus duplikasinya tetapi tidak difilter oleh allowlist model. Itu diperlakukan sebagai niat operator yang eksplisit.
• Jika run saat ini sudah berada pada fallback terkonfigurasi dalam keluarga provider yang sama, OpenClaw tetap menggunakan rantai terkonfigurasi penuh.
• Jika run saat ini berada pada provider yang berbeda dari konfigurasi dan model saat ini belum menjadi bagian dari rantai fallback terkonfigurasi, OpenClaw tidak menambahkan fallback terkonfigurasi yang tidak terkait dari provider lain.
• Ketika run dimulai dari override, primary yang dikonfigurasi ditambahkan di akhir agar rantai dapat kembali ke default normal setelah kandidat sebelumnya habis.

​

Error mana yang memajukan fallback

• kegagalan auth
• batas laju dan habisnya cooldown
• error overloaded/provider sibuk
• error failover berbentuk timeout
• penonaktifan billing
• LiveSessionModelSwitchError, yang dinormalisasi ke jalur failover agar model persisten yang usang tidak membuat loop percobaan ulang luar
• error tidak dikenali lainnya ketika masih ada kandidat tersisa

• pembatalan eksplisit yang tidak berbentuk timeout/failover
• error overflow konteks yang harus tetap berada dalam logika compaction/percobaan ulang (misalnya request_too_large, INVALID_ARGUMENT: input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, The input is too long for the model, atau ollama error: context length exceeded)
• error tak dikenal terakhir ketika tidak ada kandidat tersisa

​

Perilaku lewati cooldown vs probe

• Kegagalan auth persisten langsung melewati seluruh provider.
• Penonaktifan billing biasanya dilewati, tetapi kandidat primary masih dapat diprobe dengan throttle agar pemulihan tetap mungkin tanpa restart.
• Kandidat primary dapat diprobe mendekati akhir cooldown, dengan throttle per provider.
• Model saudara fallback provider yang sama dapat dicoba meskipun sedang cooldown ketika kegagalannya tampak transien (rate_limit, overloaded, atau tidak diketahui). Ini terutama relevan ketika batas laju dicakup ke model dan model saudara mungkin masih dapat pulih segera.
• Probe cooldown transien dibatasi satu per provider per run fallback agar satu provider tidak menghambat fallback lintas provider.

​

Override sesi dan peralihan model langsung

• Hanya perubahan model eksplisit yang digerakkan pengguna yang menandai live switch tertunda. Itu mencakup /model, session_status(model=...), dan sessions.patch.
• Perubahan model yang digerakkan sistem seperti rotasi fallback, override heartbeat, atau compaction tidak pernah menandai live switch tertunda dengan sendirinya.
• Sebelum percobaan ulang fallback dimulai, runner balasan memersistenkan field override fallback yang dipilih ke entri sesi.
• Rekonsiliasi sesi langsung lebih mengutamakan override sesi yang dipersistenkan daripada field model runtime yang usang.
• Jika percobaan fallback gagal, runner me-roll back hanya field override yang ditulisnya, dan hanya jika field itu masih cocok dengan kandidat gagal tersebut.

1. Primary gagal.
2. Kandidat fallback dipilih di memori.
3. Penyimpanan sesi masih menyatakan primary lama.
4. Rekonsiliasi sesi langsung membaca state sesi yang usang.
5. Percobaan ulang dibenturkan kembali ke model lama sebelum percobaan fallback dimulai.

​

Observabilitas dan ringkasan kegagalan

• provider/model yang dicoba
• alasan (rate_limit, overloaded, billing, auth, model_not_found, dan alasan failover serupa)
• status/kode opsional
• ringkasan error yang dapat dibaca manusia

• batas laju yang dicakup model tetapi tidak terkait diabaikan untuk rantai provider/model yang dicoba
• jika blok yang tersisa adalah batas laju yang dicakup model yang cocok, OpenClaw melaporkan waktu kedaluwarsa cocok terakhir yang masih memblokir model itu

​

Konfigurasi terkait

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• perutean agents.defaults.imageModel