Pengalihan model saat gagal

OpenClaw menangani kegagalan dalam dua tahap:

1. Rotasi profil autentikasi dalam penyedia saat ini.
2. Fallback model ke model berikutnya dalam agents.defaults.model.fallbacks.

Dokumen ini menjelaskan aturan runtime dan data yang mendukungnya.

Alur runtime

Untuk eksekusi teks normal, OpenClaw mengevaluasi kandidat dalam urutan ini:

Ini sengaja lebih sempit daripada "simpan dan pulihkan seluruh sesi". Runner balasan hanya mempertahankan field pilihan model yang dimilikinya untuk fallback:

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

Itu mencegah percobaan ulang fallback yang gagal menimpa mutasi sesi lain yang lebih baru dan tidak terkait, seperti perubahan manual /model 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.primary menggunakan agents.defaults.model.fallbacks.
• Primer agen: agents.list[].model bersifat ketat kecuali objek model agen tersebut menyertakan fallbacks sendiri. Gunakan fallbacks: [] untuk membuat perilaku ketat eksplisit, atau berikan daftar tidak kosong untuk mengikutkan 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 tanpa memeriksa primer pada setiap pesan, tetapi OpenClaw secara berkala memeriksa asal yang dikonfigurasi lagi dan menghapus override otomatis saat pulih. /new, /reset, dan sessions.reset juga menghapus override bersumber otomatis. Heartbeat berjalan tanpa heartbeat.model eksplisit menghapus override otomatis langsung ketika asalnya tidak lagi cocok dengan default yang dikonfigurasi saat ini.
• Override sesi pengguna: /model, pemilih model, session_status(model=...), dan sessions.patch menulis modelOverrideSource: "user". Itu adalah pilihan sesi persis. Jika penyedia/model yang dipilih gagal sebelum menghasilkan balasan, OpenClaw melaporkan kegagalan alih-alih menjawab dari fallback yang dikonfigurasi dan tidak terkait.
• Override sesi lama: entri sesi lama mungkin memiliki modelOverride tanpa modelOverrideSource. OpenClaw memperlakukannya sebagai override pengguna agar pilihan lama yang eksplisit tidak diam-diam diubah menjadi perilaku fallback.
• Model payload Cron: payload.model / --model tugas cron adalah primer tugas, bukan override sesi pengguna. Ini menggunakan fallback yang dikonfigurasi kecuali tugas menyediakan payload.fallbacks; payload.fallbacks: [] membuat eksekusi cron ketat.

Interval pemeriksaan primer fallback otomatis adalah lima menit dan tidak dapat dikonfigurasi. OpenClaw mengingat pemeriksaan terbaru per sesi dan model primer sehingga primer yang gagal tidak dicoba ulang pada setiap giliran. OpenClaw mengirim pemberitahuan yang terlihat ketika sesi berpindah ke fallback dan pemberitahuan lain ketika kembali ke primer yang dipilih; OpenClaw tidak mengulang pemberitahuan pada setiap giliran fallback yang lengket.

Cache lewati kegagalan autentikasi

Secara default, setiap giliran baru mempertahankan perilaku percobaan ulang fallback yang ada: OpenClaw akan mencoba setiap kandidat fallback yang dikonfigurasi lagi, termasuk kandidat non-primer yang baru-baru ini gagal dengan auth atau auth_permanent.

Operator yang lebih suka menekan kegagalan autentikasi berulang tersebut dapat ikut serta dengan:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

Saat diaktifkan, OpenClaw mencatat marker lewati dalam memori yang berlingkup sesi untuk kandidat fallback non-primer setelah kegagalan kelas autentikasi. Marker tersebut dikunci berdasarkan id sesi, penyedia, dan model. Kandidat primer tidak pernah dilewati, sehingga pilihan model pengguna eksplisit tetap memunculkan galat autentikasi sebenarnya. Cache bersifat lokal proses dan dihapus saat Gateway dimulai ulang.

Nilainya adalah TTL dalam milidetik. 0 atau nilai yang tidak diatur menonaktifkan cache. Nilai positif dibatasi antara 1 detik dan 10 menit.

Pemberitahuan fallback yang terlihat pengguna

Ketika sesi berpindah ke fallback yang dipilih otomatis, OpenClaw mengirim pemberitahuan status di permukaan balasan yang sama:

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

Ketika pemeriksaan berikutnya berhasil dan sesi kembali ke primer yang dipilih, OpenClaw mengirim:

↪️ Model Fallback cleared: <primary> (was <fallback>)

Pemberitahuan ini adalah pesan operasional, bukan konten asisten. Pemberitahuan dikirim sekali per perubahan status, termasuk giliran yang hanya memiliki efek samping jika memungkinkan, tetapi giliran fallback yang lengket tidak mengulanginya. Pengiriman melewati supresi balasan sumber normal, pemberitahuan tidak memakai slot balasan asisten pertama untuk channel berutas, dan dikecualikan dari teks-ke-ucapan serta ekstraksi komitmen.

Penyimpanan autentikasi (kunci + OAuth)

OpenClaw menggunakan profil autentikasi untuk kunci API dan token OAuth.

• Secret dan status routing autentikasi runtime berada di ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• Konfigurasi auth.profiles / auth.order adalah metadata + routing saja (tanpa secret).
• File OAuth lama yang hanya diimpor: ~/.openclaw/credentials/oauth.json (diimpor ke store autentikasi per agen pada penggunaan pertama).
• File lama auth-profiles.json, auth-state.json, dan auth.json per agen diimpor oleh openclaw doctor --fix.

Detail lebih lanjut: OAuth

Jenis kredensial:

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

ID profil

Login OAuth membuat profil yang berbeda sehingga beberapa akun dapat hidup berdampingan.

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

Profil berada di store profil autentikasi openclaw-agent.sqlite per agen.

Urutan rotasi

Ketika 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 terlebih dahulu, dalam setiap jenis).
• Profil cooldown/dinonaktifkan dipindahkan ke akhir, diurutkan berdasarkan kedaluwarsa terdekat.

Kelengketan sesi (ramah cache)

OpenClaw menyematkan profil autentikasi yang dipilih per sesi untuk menjaga 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

Pilihan manual melalui /model …@<profileId> menetapkan override pengguna untuk sesi tersebut dan tidak dirotasi otomatis hingga sesi baru dimulai.

Langganan OpenAI Codex plus cadangan kunci API

Untuk model agen OpenAI, autentikasi dan runtime terpisah. openai/gpt-* tetap berada di harness Codex sementara autentikasi dapat merotasi antara profil langganan Codex dan cadangan kunci API OpenAI.

Gunakan auth.order.openai untuk urutan yang terlihat pengguna:

{  auth: {    order: {      openai: ["openai:user@example.com", "openai:api-key-backup"],    },  },}

Gunakan openai:* untuk profil OAuth ChatGPT/Codex dan profil kunci API OpenAI. Ketika langganan mencapai batas penggunaan Codex, OpenClaw mencatat waktu reset persis ketika Codex menyediakannya, mencoba profil autentikasi berurutan berikutnya, dan menjaga eksekusi tetap di dalam harness Codex. Setelah waktu reset berlalu, profil langganan memenuhi syarat lagi dan pilihan otomatis berikutnya dapat kembali ke profil tersebut.

Gunakan profil yang disematkan pengguna hanya ketika Anda ingin memaksa satu akun/kunci untuk sesi tersebut. Profil yang disematkan pengguna sengaja ketat dan tidak diam-diam melompat ke profil lain.

Cooldown

Ketika profil gagal karena galat autentikasi/batas laju (atau timeout yang tampak seperti pembatasan laju), OpenClaw menandainya dalam cooldown dan berpindah ke profil berikutnya.

Cooldown menggunakan backoff eksponensial:

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

Status disimpan dalam status auth SQLite per agen di bawah usageStats:

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

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 lama) dan berotasi ke profil/penyedia berikutnya.

Status disimpan dalam status auth SQLite per agen:

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

Default:

• Backoff penagihan dimulai pada 5 jam, berlipat dua untuk setiap kegagalan penagihan, dan dibatasi pada 24 jam.
• Penghitung backoff direset jika profil tidak gagal selama 24 jam (dapat dikonfigurasi).
• Percobaan ulang karena kelebihan beban mengizinkan 1 rotasi profil penyedia yang sama sebelum fallback model.
• Percobaan ulang karena kelebihan beban menggunakan backoff 0 md secara default.

Fallback model

Jika semua profil untuk sebuah penyedia gagal, OpenClaw berpindah ke model berikutnya di agents.defaults.model.fallbacks. Ini berlaku untuk kegagalan auth, batas laju, dan timeout yang telah menghabiskan rotasi profil (kesalahan lain tidak memajukan fallback). Kesalahan penyedia yang tidak mengekspos detail yang cukup tetap diberi label secara tepat dalam status fallback: empty_response berarti penyedia tidak mengembalikan pesan atau status yang dapat digunakan, no_error_details berarti penyedia secara eksplisit mengembalikan Unknown error (no error details in response), dan unclassified berarti OpenClaw mempertahankan pratinjau mentah tetapi belum ada pengklasifikasi yang cocok.

Kesalahan kelebihan beban dan batas laju ditangani lebih agresif daripada cooldown penagihan. Secara default, OpenClaw mengizinkan satu percobaan ulang profil auth penyedia yang sama, lalu beralih ke fallback model terkonfigurasi berikutnya tanpa menunggu. Sinyal penyedia sibuk seperti ModelNotReadyException masuk ke bucket kelebihan beban tersebut. Sesuaikan ini dengan auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs, dan auth.cooldowns.rateLimitedProfileRotations.

Ketika sebuah run dimulai dari primary default terkonfigurasi, primary tugas cron, primary agen dengan fallback eksplisit, atau override fallback yang dipilih otomatis, OpenClaw dapat menelusuri rantai fallback terkonfigurasi yang sesuai. Primary agen tanpa fallback eksplisit dan pilihan pengguna eksplisit (misalnya /model ollama/qwen3.5:27b, pemilih model, sessions.patch, atau override penyedia/model CLI satu kali) bersifat ketat: jika penyedia/model tersebut tidak dapat dijangkau atau gagal sebelum menghasilkan balasan, OpenClaw melaporkan kegagalan tersebut alih-alih menjawab dari fallback yang tidak terkait.

Aturan rantai kandidat

OpenClaw membangun daftar kandidat dari provider/model yang saat ini diminta ditambah fallback terkonfigurasi.

Kesalahan yang memajukan fallback

Perilaku lewati cooldown vs probe

Ketika setiap profil auth untuk sebuah penyedia sudah berada dalam cooldown, OpenClaw tidak otomatis melewati penyedia tersebut selamanya. OpenClaw membuat keputusan per kandidat:

Override sesi dan pengalihan model langsung

Perubahan model sesi adalah status bersama. Runner aktif, perintah /model, pembaruan compaction/sesi, dan rekonsiliasi sesi langsung semuanya membaca atau menulis bagian dari entri sesi yang sama.

Itu berarti percobaan ulang fallback harus berkoordinasi dengan pengalihan model langsung:

• Hanya perubahan model yang didorong pengguna secara eksplisit yang menandai pengalihan langsung tertunda. Itu mencakup /model, session_status(model=...), dan sessions.patch.
• Perubahan model yang didorong sistem seperti rotasi fallback, override Heartbeat, atau Compaction tidak pernah menandai pengalihan langsung tertunda sendiri.
• Override model yang didorong pengguna diperlakukan sebagai pilihan tepat untuk kebijakan fallback, sehingga penyedia terpilih yang tidak dapat dijangkau muncul sebagai kegagalan, bukan disamarkan oleh agents.defaults.model.fallbacks.
• Sebelum percobaan ulang fallback dimulai, runner balasan mempertahankan kolom override fallback yang dipilih ke entri sesi.
• Override fallback otomatis tetap dipilih pada giliran berikutnya sehingga OpenClaw tidak memprobe primary yang diketahui buruk pada setiap pesan. OpenClaw secara berkala memprobe origin terkonfigurasi lagi dan menghapus override otomatis ketika pulih; /new, /reset, dan sessions.reset langsung menghapus override yang bersumber otomatis.
• Balasan pengguna mengumumkan transisi fallback dan pemulihan fallback yang dihapus satu kali per perubahan status. Giliran fallback yang lengket tidak mengulang pemberitahuan.
• /status menampilkan model yang dipilih dan, ketika status fallback berbeda, model fallback aktif serta alasannya.
• Rekonsiliasi sesi langsung lebih memilih override sesi persisten daripada kolom model runtime yang usang.
• Jika kesalahan pengalihan langsung menunjuk ke kandidat berikutnya dalam rantai fallback aktif, OpenClaw langsung melompat ke model yang dipilih tersebut alih-alih menelusuri kandidat yang tidak terkait terlebih dahulu.
• Jika percobaan fallback gagal, runner hanya mengembalikan kolom override yang ditulisnya, dan hanya jika kolom tersebut masih cocok dengan kandidat yang gagal tersebut.

Ini mencegah race klasik:

Override fallback persisten menutup jendela tersebut, dan rollback yang sempit menjaga perubahan sesi manual atau runtime yang lebih baru tetap utuh.

Observabilitas dan ringkasan kegagalan

runWithModelFallback(...) mencatat detail per percobaan yang memasok log dan pesan cooldown yang terlihat pengguna:

• penyedia/model yang dicoba
• alasan (rate_limit, overloaded, billing, auth, model_not_found, dan alasan failover serupa)
• status/kode opsional
• ringkasan kesalahan yang mudah dibaca manusia

Log terstruktur model_fallback_decision juga menyertakan kolom datar fallbackStep* ketika kandidat gagal, dilewati, atau fallback berikutnya berhasil. Kolom ini membuat transisi yang dicoba menjadi eksplisit (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome) sehingga eksportir log dan diagnostik dapat merekonstruksi kegagalan primary bahkan ketika fallback terminal juga gagal.

Ketika setiap kandidat gagal, OpenClaw melempar FallbackSummaryError. Runner balasan luar dapat menggunakannya untuk membangun pesan yang lebih spesifik seperti "semua model sementara terkena batas laju" dan menyertakan kedaluwarsa cooldown paling awal ketika diketahui.

Ringkasan cooldown tersebut sadar model:

• batas laju berbasis model yang tidak terkait diabaikan untuk rantai penyedia/model yang dicoba
• jika blok yang tersisa adalah batas laju berbasis model yang cocok, OpenClaw melaporkan kedaluwarsa cocok terakhir yang masih memblokir model tersebut

Konfigurasi terkait

Lihat Konfigurasi Gateway untuk:

• 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

Lihat Model untuk ikhtisar pemilihan model dan fallback yang lebih luas.