OpenClaw menangani kegagalan dalam dua tahap:Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
- Rotasi profil autentikasi dalam penyedia saat ini.
- Fallback model ke model berikutnya di
agents.defaults.model.fallbacks.
Alur runtime
Untuk eksekusi teks normal, OpenClaw mengevaluasi kandidat dalam urutan ini:Bangun rantai kandidat
Bangun rantai kandidat model dari pilihan model saat ini dan kebijakan fallback untuk sumber pilihan tersebut. Default yang dikonfigurasi, primer tugas cron, dan model fallback yang dipilih otomatis dapat menggunakan fallback yang dikonfigurasi; pilihan sesi pengguna eksplisit bersifat ketat.
Lanjutkan pada error yang layak failover
Jika penyedia tersebut habis dengan error yang layak failover, pindah ke kandidat model berikutnya.
Pertahankan override fallback
Pertahankan override fallback yang dipilih sebelum percobaan ulang dimulai agar pembaca sesi lain melihat penyedia/model yang sama dengan yang akan digunakan runner. Override model yang dipertahankan ditandai
modelOverrideSource: "auto".Rollback secara sempit pada kegagalan
Jika kandidat fallback gagal, rollback hanya field override sesi milik fallback ketika field tersebut masih cocok dengan kandidat yang gagal itu.
providerOverridemodelOverridemodelOverrideSourceauthProfileOverrideauthProfileOverrideSourceauthProfileOverrideCompactionCount
/model manual atau pembaruan rotasi sesi yang terjadi saat percobaan sedang berjalan.
Kebijakan sumber pilihan
OpenClaw memisahkan penyedia/model yang dipilih dari alasan pemilihannya. Sumber tersebut mengontrol apakah rantai fallback diizinkan:- Default yang dikonfigurasi:
agents.defaults.model.primarymenggunakanagents.defaults.model.fallbacks. - Primer agen:
agents.list[].modelbersifat ketat kecuali objek model agen tersebut menyertakanfallbacksmiliknya sendiri. Gunakanfallbacks: []untuk membuat perilaku ketat eksplisit, atau sediakan daftar yang tidak kosong untuk mengikutsertakan agen tersebut ke fallback model. - Override fallback otomatis: fallback runtime menulis
providerOverride,modelOverride,modelOverrideSource: "auto", dan model asal yang dipilih sebelum mencoba ulang. Override otomatis itu dapat terus menelusuri rantai fallback yang dikonfigurasi dan dihapus oleh/new,/reset, dansessions.reset. Eksekusi Heartbeat tanpaheartbeat.modeleksplisit juga menghapus override otomatis langsung ketika asalnya tidak lagi cocok dengan default terkonfigurasi saat ini. - Override sesi pengguna:
/model, pemilih model,session_status(model=...), dansessions.patchmenulismodelOverrideSource: "user". Itu adalah pilihan sesi persis. Jika penyedia/model yang dipilih gagal sebelum menghasilkan balasan, OpenClaw melaporkan kegagalan alih-alih menjawab dari fallback terkonfigurasi yang tidak terkait. - Override sesi lama: entri sesi lama mungkin memiliki
modelOverridetanpamodelOverrideSource. OpenClaw memperlakukannya sebagai override pengguna agar pilihan lama yang eksplisit tidak diam-diam dikonversi menjadi perilaku fallback. - Model payload Cron:
payload.model/--modeltugas cron adalah primer tugas, bukan override sesi pengguna. Itu menggunakan fallback yang dikonfigurasi kecuali tugas menyediakanpayload.fallbacks;payload.fallbacks: []membuat eksekusi cron bersifat ketat.
Penyimpanan autentikasi (kunci + OAuth)
OpenClaw menggunakan profil autentikasi untuk kunci API dan token OAuth.- Rahasia berada di
~/.openclaw/agents/<agentId>/agent/auth-profiles.json(lama:~/.openclaw/agent/auth-profiles.json). - Status perutean autentikasi runtime berada di
~/.openclaw/agents/<agentId>/agent/auth-state.json. - Konfigurasi
auth.profiles/auth.orderadalah metadata + perutean saja (tanpa rahasia). - File OAuth lama khusus impor:
~/.openclaw/credentials/oauth.json(diimpor keauth-profiles.jsonsaat pertama kali digunakan).
type: "api_key"→{ provider, key }type: "oauth"→{ provider, access, refresh, expires, email? }(+projectId/enterpriseUrluntuk beberapa penyedia)
ID profil
Login OAuth membuat profil terpisah agar beberapa akun dapat berdampingan.- Default:
provider:defaultketika tidak ada email yang tersedia. - OAuth dengan email:
provider:<email>(misalnyagoogle-antigravity:user@gmail.com).
~/.openclaw/agents/<agentId>/agent/auth-profiles.json di bawah profiles.
Urutan rotasi
Ketika sebuah penyedia memiliki beberapa profil, OpenClaw memilih urutan seperti ini:
Jika tidak ada urutan eksplisit yang dikonfigurasi, OpenClaw menggunakan urutan round-robin:
- Kunci primer: jenis profil (OAuth sebelum kunci API).
- Kunci sekunder:
usageStats.lastUsed(yang paling lama lebih dulu, dalam setiap jenis). - Profil cooldown/dinonaktifkan dipindahkan ke akhir, diurutkan berdasarkan waktu berakhir terdekat.
Kelekatan sesi (ramah cache)
OpenClaw menyematkan profil auth yang dipilih per sesi agar cache penyedia tetap hangat. OpenClaw tidak merotasi pada setiap permintaan. Profil yang disematkan digunakan kembali hingga:- sesi direset (
/new//reset) - compaction selesai (jumlah compaction bertambah)
- profil berada dalam cooldown/dinonaktifkan
/model …@<profileId> menetapkan override pengguna untuk sesi tersebut dan tidak dirotasi otomatis hingga sesi baru dimulai.
Profil yang disematkan otomatis (dipilih oleh router sesi) diperlakukan sebagai preferensi: profil tersebut dicoba terlebih dahulu, tetapi OpenClaw dapat merotasi ke profil lain saat terjadi batas laju/timeout. Ketika profil asli tersedia kembali, eksekusi baru dapat memprioritaskannya lagi tanpa mengubah model atau runtime yang dipilih. Profil yang disematkan pengguna tetap terkunci ke profil tersebut; jika gagal dan fallback model dikonfigurasi, OpenClaw berpindah ke model berikutnya alih-alih mengganti profil.
Langganan OpenAI Codex plus cadangan API key
Untuk model agen OpenAI, auth dan runtime terpisah.openai/gpt-* tetap berada di
harness Codex sementara auth dapat berotasi antara profil langganan Codex dan
cadangan API key OpenAI.
Gunakan auth.order.openai untuk urutan yang terlihat oleh pengguna:
openai-codex:*. Cadangan API key yang diurutkan dapat berupa profil API key
openai:* biasa. Ketika langganan mencapai batas penggunaan Codex,
OpenClaw mencatat waktu reset persis saat Codex menyediakannya, mencoba profil
auth berikutnya dalam urutan, dan menjaga eksekusi tetap di dalam harness Codex. Setelah waktu reset
berlalu, profil langganan memenuhi syarat lagi dan pemilihan otomatis berikutnya
dapat kembali ke profil tersebut.
Gunakan profil yang disematkan pengguna hanya saat Anda ingin memaksa satu akun/key untuk
sesi tersebut. Profil yang disematkan pengguna sengaja dibuat ketat dan tidak diam-diam melompat
ke profil lain.
Cooldown
Ketika profil gagal karena kesalahan auth/batas laju (atau timeout yang terlihat seperti pembatasan laju), OpenClaw menandainya dalam cooldown dan berpindah ke profil berikutnya.Apa yang masuk ke kategori batas laju / timeout
Apa yang masuk ke kategori batas laju / timeout
Kategori batas laju itu lebih luas daripada
429 biasa: kategori ini juga mencakup pesan penyedia seperti Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, throttled, resource exhausted, dan batas jendela penggunaan berkala seperti weekly/monthly limit reached.Kesalahan format/permintaan tidak valid biasanya terminal karena mencoba ulang payload yang sama akan gagal dengan cara yang sama, jadi OpenClaw menampilkannya alih-alih merotasi profil autentikasi. Jalur perbaikan coba ulang yang diketahui dapat ikut serta secara eksplisit: misalnya kegagalan validasi ID panggilan alat Cloud Code Assist dibersihkan dan dicoba ulang sekali melalui kebijakan allowFormatRetry. Kesalahan alasan berhenti yang kompatibel dengan OpenAI seperti Unhandled stop reason: error, stop reason: error, dan reason: error diklasifikasikan sebagai sinyal timeout/failover.Teks server generik juga dapat masuk ke kategori timeout itu ketika sumbernya cocok dengan pola sementara yang dikenal. Misalnya, pesan stream-wrapper pi-ai polos An unknown error occurred diperlakukan sebagai layak failover untuk setiap penyedia karena pi-ai memancarkannya ketika stream penyedia berakhir dengan stopReason: "aborted" atau stopReason: "error" tanpa detail spesifik. Payload JSON api_error dengan teks server sementara seperti internal server error, unknown error, 520, upstream error, atau backend error juga diperlakukan sebagai timeout yang layak failover.Teks upstream generik khusus OpenRouter seperti Provider returned error polos diperlakukan sebagai timeout hanya ketika konteks penyedianya benar-benar OpenRouter. Teks fallback internal generik seperti LLM request failed with an unknown error. tetap konservatif dan tidak memicu failover dengan sendirinya.Batas retry-after SDK
Batas retry-after SDK
Beberapa SDK penyedia mungkin, jika tidak dibatasi, tidur selama jendela
Retry-After yang panjang sebelum mengembalikan kontrol ke OpenClaw. Untuk SDK berbasis Stainless seperti Anthropic dan OpenAI, OpenClaw membatasi penantian retry-after-ms / retry-after internal SDK pada 60 detik secara default dan langsung menampilkan respons yang dapat dicoba ulang yang lebih panjang agar jalur failover ini dapat berjalan. Sesuaikan atau nonaktifkan batas tersebut dengan OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS; lihat Perilaku coba ulang.Cooldown berskala model
Cooldown berskala model
Cooldown batas laju juga dapat berskala model:
- OpenClaw mencatat
cooldownModeluntuk kegagalan batas laju ketika ID model yang gagal diketahui. - Model saudara pada penyedia yang sama masih dapat dicoba ketika cooldown dibatasi ke model lain.
- Jendela penagihan/dinonaktifkan tetap memblokir seluruh profil di seluruh model.
- 1 menit
- 5 menit
- 25 menit
- 1 jam (batas)
auth-state.json di bawah usageStats:
Penonaktifan penagihan
Kegagalan penagihan/kredit (misalnya “insufficient credits” / “credit balance too low”) diperlakukan sebagai layak failover, tetapi biasanya tidak bersifat sementara. Alih-alih cooldown singkat, OpenClaw menandai profil sebagai dinonaktifkan (dengan backoff yang lebih panjang) dan merotasi ke profil/penyedia berikutnya.Tidak setiap respons yang berbentuk penagihan adalah
402, dan tidak setiap HTTP 402 masuk ke sini. OpenClaw mempertahankan teks penagihan eksplisit di jalur penagihan bahkan ketika penyedia mengembalikan 401 atau 403 sebagai gantinya, tetapi pencocok khusus penyedia tetap dibatasi pada penyedia yang memilikinya (misalnya OpenRouter 403 Key limit exceeded).Sementara itu, error 402 sementara untuk jendela penggunaan dan batas pengeluaran organisasi/workspace diklasifikasikan sebagai rate_limit saat pesannya tampak dapat dicoba ulang (misalnya weekly usage limit exhausted, daily limit reached, resets tomorrow, atau organization spending limit exceeded). Error tersebut tetap berada di jalur cooldown/failover singkat, bukan jalur penonaktifan penagihan yang panjang.auth-state.json:
- Backoff penagihan dimulai dari 5 jam, berlipat dua untuk setiap kegagalan penagihan, dan dibatasi hingga 24 jam.
- Penghitung backoff direset jika profil tidak gagal selama 24 jam (dapat dikonfigurasi).
- Percobaan ulang akibat overload mengizinkan 1 rotasi profil provider yang sama sebelum fallback model.
- Percobaan ulang akibat overload menggunakan backoff 0 md secara default.
Fallback model
Jika semua profil untuk suatu provider gagal, OpenClaw berpindah ke model berikutnya diagents.defaults.model.fallbacks. Ini berlaku untuk kegagalan auth, batas rate, dan timeout yang telah menghabiskan rotasi profil (error lain tidak memajukan fallback). Error provider yang tidak menampilkan detail yang cukup tetap diberi label secara presisi dalam state fallback: empty_response berarti provider tidak mengembalikan pesan atau status yang dapat digunakan, no_error_details berarti provider secara eksplisit mengembalikan Unknown error (no error details in response), dan unclassified berarti OpenClaw mempertahankan pratinjau mentah tetapi belum ada classifier yang cocok.
Error overload dan batas rate ditangani lebih agresif daripada cooldown penagihan. Secara default, OpenClaw mengizinkan satu percobaan ulang profil auth pada provider yang sama, lalu beralih ke fallback model berikutnya yang dikonfigurasi tanpa menunggu. Sinyal provider sibuk seperti ModelNotReadyException masuk ke bucket overload tersebut. Sesuaikan ini dengan auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs, dan auth.cooldowns.rateLimitedProfileRotations.
Saat sebuah run dimulai dari primary default yang dikonfigurasi, primary cron job, primary agent dengan fallback eksplisit, atau override fallback yang dipilih otomatis, OpenClaw dapat menelusuri rantai fallback terkonfigurasi yang sesuai. Primary agent tanpa fallback eksplisit dan pilihan pengguna eksplisit (misalnya /model ollama/qwen3.5:27b, pemilih model, sessions.patch, atau override provider/model CLI sekali pakai) bersifat ketat: jika provider/model tersebut tidak dapat dijangkau atau gagal sebelum menghasilkan balasan, OpenClaw melaporkan kegagalan alih-alih menjawab dari fallback yang tidak terkait.
Aturan rantai kandidat
OpenClaw membangun daftar kandidat dariprovider/model yang saat ini diminta plus fallback yang dikonfigurasi.
Aturan
Aturan
- Model yang diminta selalu berada di urutan pertama.
- Fallback eksplisit yang dikonfigurasi dideduplikasi tetapi tidak difilter oleh allowlist model. Fallback tersebut diperlakukan sebagai niat operator eksplisit.
- Jika run saat ini sudah berada pada fallback yang dikonfigurasi dalam keluarga provider yang sama, OpenClaw tetap menggunakan seluruh rantai terkonfigurasi.
- Jika tidak ada override fallback eksplisit yang diberikan, fallback yang dikonfigurasi dicoba sebelum primary yang dikonfigurasi meskipun model yang diminta menggunakan provider berbeda.
- Jika tidak ada override fallback eksplisit yang diberikan ke runner fallback, primary yang dikonfigurasi ditambahkan di akhir agar rantai dapat kembali menetap ke default normal setelah kandidat sebelumnya habis.
- Saat pemanggil memberikan
fallbacksOverride, runner menggunakan tepat model yang diminta plus daftar override tersebut. Daftar kosong menonaktifkan fallback model dan mencegah primary yang dikonfigurasi ditambahkan sebagai target percobaan ulang tersembunyi.
Error mana yang memajukan fallback
- Berlanjut pada
- Tidak berlanjut pada
- kegagalan auth
- batas rate dan habisnya cooldown
- error overload/provider sibuk
- error failover berbentuk timeout
- penonaktifan penagihan
LiveSessionModelSwitchError, yang dinormalisasi ke jalur failover agar model tersimpan yang sudah usang tidak membuat loop percobaan ulang luar- error lain yang tidak dikenali saat masih ada kandidat tersisa
Perilaku skip cooldown vs probe
Saat setiap profil auth untuk suatu provider sudah berada dalam cooldown, OpenClaw tidak otomatis melewati provider tersebut selamanya. OpenClaw membuat keputusan per kandidat:Keputusan per kandidat
Keputusan per kandidat
- Kegagalan auth persisten langsung melewati seluruh provider.
- Penonaktifan penagihan biasanya dilewati, tetapi kandidat primary masih dapat diprobe dengan throttle agar pemulihan mungkin dilakukan tanpa restart.
- Kandidat primary dapat diprobe mendekati berakhirnya cooldown, dengan throttle per provider.
- Sibling fallback pada provider yang sama dapat dicoba meskipun ada cooldown saat kegagalan tampak sementara (
rate_limit,overloaded, atau tidak diketahui). Ini sangat relevan saat batas rate bersifat khusus model dan model sibling masih dapat segera pulih. - Probe cooldown sementara dibatasi satu per provider per run fallback agar satu provider tidak menghambat fallback lintas-provider.
Override sesi dan penggantian model live
Perubahan model sesi adalah state bersama. Runner aktif, perintah/model, pembaruan Compaction/sesi, dan rekonsiliasi sesi live semuanya membaca atau menulis bagian dari entri sesi yang sama.
Artinya, percobaan ulang fallback harus berkoordinasi dengan penggantian model live:
- Hanya perubahan model eksplisit yang digerakkan pengguna yang menandai penggantian live tertunda. Ini mencakup
/model,session_status(model=...), dansessions.patch. - Perubahan model yang digerakkan sistem seperti rotasi fallback, override Heartbeat, atau Compaction tidak pernah menandai penggantian live tertunda sendiri.
- Override model yang digerakkan pengguna diperlakukan sebagai pilihan persis untuk kebijakan fallback, sehingga provider terpilih yang tidak dapat dijangkau muncul sebagai kegagalan alih-alih disamarkan oleh
agents.defaults.model.fallbacks. - Sebelum percobaan ulang fallback dimulai, runner balasan mempertahankan field override fallback yang dipilih ke entri sesi.
- Override fallback otomatis tetap dipilih pada giliran berikutnya sehingga OpenClaw tidak memprobe primary yang diketahui bermasalah pada setiap pesan.
/new,/reset, dansessions.resetmenghapus override yang bersumber otomatis dan mengembalikan sesi ke default yang dikonfigurasi. /statusmenampilkan model yang dipilih dan, saat state fallback berbeda, model fallback aktif serta alasannya.- Rekonsiliasi sesi live lebih memilih override sesi yang dipertahankan daripada field model runtime yang usang.
- Jika error penggantian live menunjuk ke kandidat berikutnya dalam rantai fallback aktif, OpenClaw langsung melompat ke model terpilih tersebut alih-alih menelusuri kandidat yang tidak terkait terlebih dahulu.
- Jika upaya fallback gagal, runner melakukan rollback hanya pada field override yang ditulisnya, dan hanya jika field tersebut masih cocok dengan kandidat yang gagal itu.
Override fallback yang dipertahankan menutup celah itu, dan rollback sempit menjaga perubahan sesi manual atau runtime yang lebih baru tetap utuh.
Observabilitas dan ringkasan kegagalan
runWithModelFallback(...) mencatat detail per upaya yang menjadi input untuk log dan pesan cooldown yang ditampilkan kepada pengguna:
- 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
model_fallback_decision juga menyertakan field fallbackStep* datar saat kandidat gagal, dilewati, atau fallback berikutnya berhasil. Field ini membuat transisi yang dicoba menjadi eksplisit (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome) sehingga eksportir log dan diagnostik dapat merekonstruksi kegagalan primary bahkan saat fallback terminal juga gagal.
Saat setiap kandidat gagal, OpenClaw melempar FallbackSummaryError. Runner balasan luar dapat menggunakannya untuk membuat pesan yang lebih spesifik seperti “semua model untuk sementara terkena batas rate” dan menyertakan waktu berakhir cooldown paling awal jika diketahui.
Ringkasan cooldown tersebut sadar model:
- batas rate khusus model yang tidak terkait diabaikan untuk rantai provider/model yang dicoba
- jika blok yang tersisa adalah batas rate khusus model yang cocok, OpenClaw melaporkan waktu berakhir terakhir yang cocok yang masih memblokir model tersebut
Konfigurasi terkait
Lihat Konfigurasi Gateway untuk:auth.profiles/auth.orderauth.cooldowns.billingBackoffHours/auth.cooldowns.billingBackoffHoursByProviderauth.cooldowns.billingMaxHours/auth.cooldowns.failureWindowHoursauth.cooldowns.overloadedProfileRotations/auth.cooldowns.overloadedBackoffMsauth.cooldowns.rateLimitedProfileRotationsagents.defaults.model.primary/agents.defaults.model.fallbacks- routing
agents.defaults.imageModel