မော်ဒယ် failover¶

OpenClaw သည် ချို့ယွင်းမှုများကို အဆင့်နှစ်ဆင့်ဖြင့် ကိုင်တွယ်သည်-

1. လက်ရှိ provider အတွင်း Auth profile လှည့်ပြောင်းခြင်း။
2. agents.defaults.model.fallbacks ထဲရှိ နောက်ထပ် မော်ဒယ်သို့ Model fallback ပြုလုပ်ခြင်း။

ဤစာတမ်းသည် runtime စည်းမျဉ်းများနှင့် ၎င်းတို့ကို ထောက်ပံ့ပေးသော ဒေတာများကို ရှင်းပြထားသည်။

Auth သိမ်းဆည်းမှု (keys + OAuth)¶

OpenClaw သည် API keys နှင့် OAuth tokens နှစ်မျိုးစလုံးအတွက် auth profiles ကို အသုံးပြုသည်။

• Secrets များကို ~/.openclaw/agents/<agentId>/agent/auth-profiles.json တွင် သိမ်းဆည်းထားသည် (legacy: ~/.openclaw/agent/auth-profiles.json)။
• Config auth.profiles / auth.order များသည် metadata + routing အတွက်သာ ဖြစ်ပြီး (secrets မပါ)။
• Legacy import-only OAuth ဖိုင်: ~/.openclaw/credentials/oauth.json (ပထမဆုံး အသုံးပြုချိန်တွင် auth-profiles.json သို့ import လုပ်သည်)။

အသေးစိတ်: /concepts/oauth

Credential အမျိုးအစားများ-

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

Profile ID များ¶

OAuth ဖြင့် login ဝင်သောအခါ အကောင့်အများအပြားကို တပြိုင်နက်တည်း ရှိနိုင်စေရန် distinct profile များကို ဖန်တီးပေးသည်။

• Default: email မရရှိနိုင်သည့်အခါ provider:default။
• Email ပါသော OAuth: provider:<email> (ဥပမာ google-antigravity:user@gmail.com)။

Profiles များကို ~/.openclaw/agents/<agentId>/agent/auth-profiles.json အောက်ရှိ profiles တွင် သိမ်းဆည်းထားသည်။

လှည့်ပြောင်းမှု အစဉ်အတိုင်း¶

Provider တစ်ခုတွင် profile အများအပြား ရှိပါက OpenClaw သည် အောက်ပါအစဉ်အတိုင်းကို ရွေးချယ်သည်-

1. အတိအလင်း config: auth.order[provider] (သတ်မှတ်ထားပါက)။
2. Config ပြုလုပ်ထားသော profiles: provider အလိုက် စစ်ထုတ်ထားသော auth.profiles။
3. သိမ်းဆည်းထားသော profiles: provider အတွက် auth-profiles.json ထဲရှိ entries များ။

အတိအလင်း အစဉ်အတိုင်း မသတ်မှတ်ထားပါက OpenClaw သည် round‑robin အစဉ်အတိုင်းကို အသုံးပြုသည်-

• Primary key: profile အမျိုးအစား (OAuth ကို API keys များထက် အရင်)။
• Secondary key: usageStats.lastUsed (အမျိုးအစားတစ်ခုစီအတွင်း အဟောင်းဆုံးမှ စတင်)။
• Cooldown/disabled profiles များကို အဆုံးဘက်သို့ ရွှေ့ပြီး သက်တမ်းကုန်ဆုံးချိန် အနီးဆုံးအလိုက် စီထားသည်။

Session stickiness (cache‑friendly)¶

OpenClaw သည် provider cache များကို နွေးထွေးစွာ ထိန်းသိမ်းထားနိုင်ရန် ရွေးချယ်ထားသော auth profile ကို session တစ်ခုချင်းစီအလိုက် pin လုပ်ထားသည်။ It does not rotate on every request. The pinned profile is reused until:

• session ကို reset လုပ်သောအခါ (/new / /reset)
• compaction ပြီးစီးပြီး (compaction count တိုးလာသောအခါ)
• profile သည် cooldown/disabled ဖြစ်သွားသောအခါ

/model …@<profileId> ဖြင့် လက်ဖြင့် ရွေးချယ်ခြင်းသည် ထို session အတွက် user override ကို သတ်မှတ်ပေးပြီး session အသစ် မစတင်မချင်း auto‑rotate မလုပ်ပါ။

session router မှ ရွေးချယ်ထားသော Auto‑pinned profile များကို preference အဖြစ်သာ သတ်မှတ်ထားသည်။ they are tried first, but OpenClaw may rotate to another profile on rate limits/timeouts. User‑pinned profiles stay locked to that profile; if it fails and model fallbacks are configured, OpenClaw moves to the next model instead of switching profiles.

OAuth “ပျောက်သွားသလို” မြင်ရနိုင်သည့် အကြောင်းရင်း¶

တူညီသော provider အတွက် OAuth profile နှင့် API key profile နှစ်ခုလုံးရှိပါက pin မလုပ်ထားလျှင် round‑robin စနစ်ကြောင့် message များအကြား profile ပြောင်းလဲနိုင်သည်။ Profile တစ်ခုတည်းကိုသာ အသုံးပြုလိုပါက:

• auth.order[provider] = ["provider:profileId"] ဖြင့် pin လုပ်ပါ၊ သို့မဟုတ်
• သင့် UI/chat surface က ထောက်ပံ့ပါက profile override ပါသော /model … ဖြင့် per‑session override ကို အသုံးပြုပါ။

Cooldown များ¶

profile တစ်ခုသည် auth / rate‑limit အမှားများကြောင့် (သို့မဟုတ် ထိုကဲ့သို့ ဖြစ်ပုံရသော timeout တစ်ခုကြောင့်) မအောင်မြင်ပါက like rate limiting), OpenClaw marks it in cooldown and moves to the next profile. Format/invalid‑request errors (for example Cloud Code Assist tool call ID validation failures) are treated as failover‑worthy and use the same cooldowns.

Cooldown များသည် exponential backoff ကို အသုံးပြုသည်-

• ၁ မိနစ်
• ၅ မိနစ်
• ၂၅ မိနစ်
• ၁ နာရီ (အများဆုံး)

State ကို auth-profiles.json အောက်ရှိ usageStats တွင် သိမ်းဆည်းထားသည်-

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

Billing ကြောင့် disable လုပ်ခြင်း¶

Billing / credit ဆိုင်ရာ မအောင်မြင်မှုများ (ဥပမာ “insufficient credits” / “credit balance too low”) ကိုလည်း failover ပြုလုပ်သင့်သည့် အခြေအနေအဖြစ် သတ်မှတ်သည်၊ သို့သော် အများအားဖြင့် ယာယီပြဿနာမဟုတ်ပါ။ အချိန်တို cooldown အစား OpenClaw သည် ထို profile ကို disabled အဖြစ် သတ်မှတ်ပြီး (ပိုရှည်သော backoff ဖြင့်) နောက်ထပ် profile / provider သို့ ပြောင်းလဲအသုံးပြုသည်။

State ကို auth-profiles.json တွင် သိမ်းဆည်းထားသည်-

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

Default များ-

• Billing backoff သည် ၅ နာရီ မှ စတင်ပြီး billing failure တစ်ကြိမ်စီအလိုက် နှစ်ဆတိုးကာ ၂၄ နာရီ တွင် အများဆုံး ရပ်တန့်သည်။
• Profile သည် ၂၄ နာရီ အတွင်း မအောင်မြင်မှု မရှိပါက backoff counter များကို reset လုပ်သည် (configurable)။

Model fallback¶

provider တစ်ခုအတွက် profile အားလုံး မအောင်မြင်ပါက OpenClaw သည် နောက်ထပ် model သို့ ပြောင်းလဲအသုံးပြုသည်။ agents.defaults.model.fallbacks. This applies to auth failures, rate limits, and timeouts that exhausted profile rotation (other errors do not advance fallback).

Run တစ်ခုကို model override (hooks သို့မဟုတ် CLI) ဖြင့် စတင်ထားပါကလည်း fallback များသည် ပြင်ဆင်ထားသည့် fallback များကို စမ်းသပ်ပြီးနောက် agents.defaults.model.primary တွင် အဆုံးသတ်သည်။

ဆက်စပ် config များ¶

အောက်ပါအကြောင်းအရာများအတွက် Gateway（ဂိတ်ဝေး） configuration ကို ကြည့်ပါ-

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel routing

မော်ဒယ် ရွေးချယ်မှုနှင့် fallback အကြောင်း အကျယ်တဝင့်ကို Models တွင် ကြည့်ပါ။