​

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 saat eksekusi dimulai dari sebuah override.

1. Resolusikan 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 tersebut habis dengan error yang layak failover, pindah ke kandidat model berikutnya.
5. Simpan 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, kembalikan hanya field override sesi milik fallback saat field tersebut masih cocok dengan kandidat gagal itu.
7. Jika setiap kandidat gagal, lempar FallbackSummaryError dengan detail per percobaan dan waktu cooldown berakhir paling cepat saat diketahui.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Penyimpanan auth (key + OAuth)

• Secret disimpan di ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (lama: ~/.openclaw/agent/auth-profiles.json).
• Config auth.profiles / auth.order hanya untuk metadata + perutean (tanpa secret).
• File OAuth lama hanya untuk 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 email tidak tersedia.
• OAuth dengan email: provider:<email> (misalnya google-antigravity:user@gmail.com).

​

Urutan rotasi

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

• Kunci utama: jenis profil (OAuth sebelum API key).
• Kunci sekunder: usageStats.lastUsed (yang paling lama lebih dulu, di dalam tiap jenis).
• Profil cooldown/dinonaktifkan dipindahkan ke akhir, diurutkan menurut waktu berakhir paling cepat.

​

Kekakuan sesi (ramah cache)

• sesi direset (/new / /reset)
• pemadatan selesai (jumlah pemadatan bertambah)
• profil sedang 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 UI/permukaan chat Anda).

​

Cooldown

• OpenClaw mencatat cooldownModel untuk kegagalan rate-limit saat id model yang gagal diketahui.
• Model saudara pada provider yang sama masih dapat dicoba saat cooldown dicakup ke model yang berbeda.
• Jendela billing/dinonaktifkan tetap memblokir seluruh profil lintas model.

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

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

​

Penonaktifan billing

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

• Backoff billing dimulai dari 5 jam, berlipat ganda per kegagalan billing, dan dibatasi pada 24 jam.
• Penghitung backoff direset 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 dideduplikasi tetapi tidak difilter menurut allowlist model. Fallback tersebut diperlakukan sebagai maksud operator yang eksplisit.
• Jika eksekusi saat ini sudah berada pada fallback terkonfigurasi dalam keluarga provider yang sama, OpenClaw tetap menggunakan rantai terkonfigurasi penuh.
• Jika eksekusi saat ini menggunakan provider yang berbeda dari config dan model saat ini belum menjadi bagian dari rantai fallback terkonfigurasi, OpenClaw tidak menambahkan fallback terkonfigurasi yang tidak terkait dari provider lain.
• Saat eksekusi dimulai dari override, model utama yang dikonfigurasi ditambahkan di akhir agar rantai dapat kembali ke default normal setelah kandidat sebelumnya habis.

​

Error mana yang memajukan fallback

• kegagalan auth
• rate limit dan cooldown yang habis
• error overloaded/provider-busy
• error failover berbentuk timeout
• penonaktifan billing
• LiveSessionModelSwitchError, yang dinormalisasi ke jalur failover sehingga model tersimpan yang usang tidak membuat loop percobaan ulang luar
• error tak dikenali lainnya saat masih ada kandidat yang tersisa

• pembatalan eksplisit yang tidak berbentuk timeout/failover
• error luapan konteks yang harus tetap berada di dalam logika pemadatan/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 saat tidak ada kandidat tersisa

​

Perilaku lewati cooldown vs probe

• Kegagalan auth persisten langsung melewati seluruh provider.
• Penonaktifan billing biasanya dilewati, tetapi kandidat utama masih dapat diprobe dengan throttle agar pemulihan tetap mungkin tanpa memulai ulang.
• Kandidat utama dapat diprobe saat mendekati berakhirnya cooldown, dengan throttle per provider.
• Model saudara pada fallback provider yang sama dapat dicoba meskipun cooldown saat kegagalannya terlihat sementara (rate_limit, overloaded, atau tidak diketahui). Ini sangat relevan saat sebuah rate limit dicakup model dan model saudara mungkin masih dapat pulih segera.
• Probe cooldown transien dibatasi satu kali per provider per eksekusi fallback agar satu provider tidak menghambat fallback lintas provider.

​

Override sesi dan peralihan model langsung

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

1. Model utama gagal.
2. Kandidat fallback dipilih di memori.
3. Penyimpanan sesi masih menyatakan model utama lama.
4. Rekonsiliasi sesi langsung membaca status sesi yang usang.
5. Percobaan ulang dipaksa 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

• rate limit yang dicakup model dan tidak terkait diabaikan untuk rantai provider/model yang dicoba
• jika sisa bloknya adalah rate limit yang cocok dan dicakup model, OpenClaw melaporkan waktu berakhir cocok terakhir yang masih memblokir model tersebut

​

Config 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
• agents.defaults.imageModel routing