جایگزینی اضطراری مدل

OpenClaw خرابی‌ها را در دو مرحله مدیریت می‌کند:

1. چرخش پروفایل احراز هویت درون provider فعلی.
2. fallback مدل به مدل بعدی در agents.defaults.model.fallbacks.

این سند قواعد زمان اجرا و داده‌هایی را که پشتوانهٔ آن‌ها هستند توضیح می‌دهد.

# جریان زمان اجرا

برای یک اجرای متنی عادی، OpenClaw گزینه‌ها را به این ترتیب ارزیابی می‌کند:

این عمداً محدودتر از «ذخیره و بازیابی کل نشست» است. runner پاسخ فقط فیلدهای انتخاب مدل را که برای fallback مالک آن‌هاست پایدار می‌کند:

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

این کار مانع می‌شود تلاش دوبارهٔ fallback شکست‌خورده، تغییرات نامرتبط و جدیدتر نشست مانند تغییرات دستی /model یا به‌روزرسانی‌های چرخش نشست را که هنگام اجرای تلاش رخ داده‌اند بازنویسی کند.

# سیاست منبع انتخاب

OpenClaw مدل/provider انتخاب‌شده را از دلیل انتخاب آن جدا می‌کند. آن منبع تعیین می‌کند که آیا زنجیرهٔ fallback مجاز است یا نه:

• پیش‌فرض پیکربندی‌شده: agents.defaults.model.primary از agents.defaults.model.fallbacks استفاده می‌کند.
• مدل اصلی agent: agents.list[].model سخت‌گیرانه است مگر اینکه شیء مدل آن agent شامل fallbacks خودش باشد. از fallbacks: [] استفاده کنید تا رفتار سخت‌گیرانه صریح شود، یا یک فهرست غیرخالی بدهید تا fallback مدل برای آن agent فعال شود.
• بازنویسی fallback خودکار: یک fallback زمان اجرا پیش از تلاش دوباره، providerOverride، modelOverride، و modelOverrideSource: "auto" را می‌نویسد. آن بازنویسی خودکار می‌تواند زنجیرهٔ fallback پیکربندی‌شده را ادامه دهد و با /new، /reset، و sessions.reset پاک می‌شود.
• بازنویسی نشست کاربر: /model، انتخاب‌گر مدل، session_status(model=...)، و sessions.patch مقدار modelOverrideSource: "user" را می‌نویسند. این یک انتخاب دقیق برای نشست است. اگر provider/model انتخاب‌شده پیش از تولید پاسخ شکست بخورد، OpenClaw به‌جای پاسخ دادن از یک fallback پیکربندی‌شدهٔ نامرتبط، خرابی را گزارش می‌کند.
• بازنویسی نشست قدیمی: ورودی‌های قدیمی‌تر نشست ممکن است modelOverride را بدون modelOverrideSource داشته باشند. OpenClaw آن‌ها را بازنویسی‌های کاربر در نظر می‌گیرد تا یک انتخاب صریح قدیمی بی‌صدا به رفتار fallback تبدیل نشود.
• مدل payload مربوط به Cron: مقدار payload.model / --model در یک کار cron، مدل اصلی کار است، نه بازنویسی نشست کاربر. مگر اینکه کار payload.fallbacks ارائه کند، از fallbackهای پیکربندی‌شده استفاده می‌کند؛ payload.fallbacks: [] اجرای cron را سخت‌گیرانه می‌کند.

# ذخیره‌سازی احراز هویت (کلیدها + OAuth)

OpenClaw هم برای کلیدهای API و هم برای توکن‌های OAuth از پروفایل‌های احراز هویت استفاده می‌کند.

• secretها در ~/.openclaw/agents/<agentId>/agent/auth-profiles.json قرار دارند (قدیمی: ~/.openclaw/agent/auth-profiles.json).
• وضعیت مسیریابی احراز هویت زمان اجرا در ~/.openclaw/agents/<agentId>/agent/auth-state.json قرار دارد.
• پیکربندی auth.profiles / auth.order فقط فراداده + مسیریابی هستند (بدون secret).
• فایل OAuth قدیمیِ فقط برای import: ~/.openclaw/credentials/oauth.json (در اولین استفاده به auth-profiles.json import می‌شود).

جزئیات بیشتر: OAuth

انواع credential:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl برای بعضی providerها)

# شناسه‌های پروفایل

ورودهای OAuth پروفایل‌های جداگانه می‌سازند تا چند حساب بتوانند هم‌زمان وجود داشته باشند.

• پیش‌فرض: provider:default وقتی ایمیلی در دسترس نیست.
• OAuth با ایمیل: provider:<email> (برای مثال google-antigravity:[email protected]).

پروفایل‌ها در ~/.openclaw/agents/<agentId>/agent/auth-profiles.json زیر profiles قرار دارند.

# ترتیب چرخش

وقتی یک provider چند پروفایل دارد، OpenClaw ترتیب را به این شکل انتخاب می‌کند:

اگر ترتیب صریحی پیکربندی نشده باشد، OpenClaw از ترتیب round-robin استفاده می‌کند:

• کلید اصلی: نوع پروفایل (OAuth پیش از کلیدهای API).
• کلید ثانویه: usageStats.lastUsed (قدیمی‌ترین ابتدا، درون هر نوع).
• پروفایل‌های در دورهٔ انتظار/غیرفعال به انتها منتقل می‌شوند و بر اساس نزدیک‌ترین زمان پایان مرتب می‌شوند.

# چسبندگی نشست (سازگار با cache)

OpenClaw برای گرم نگه داشتن cacheهای provider، پروفایل احراز هویت انتخاب‌شده را برای هر نشست pin می‌کند. در هر درخواست چرخش انجام نمی‌دهد. پروفایل pin‌شده دوباره استفاده می‌شود تا زمانی که:

• نشست reset شود (/new / /reset)
• یک Compaction کامل شود (شمارندهٔ Compaction افزایش یابد)
• پروفایل در دورهٔ انتظار/غیرفعال باشد

انتخاب دستی از طریق /model …@<profileId> یک بازنویسی کاربر برای آن نشست تنظیم می‌کند و تا شروع نشست جدید به‌صورت خودکار چرخش نمی‌کند.

# چرا OAuth ممکن است «گم‌شده به نظر برسد»

اگر برای یک provider هم پروفایل OAuth و هم پروفایل کلید API داشته باشید، round-robin می‌تواند بین پیام‌ها میان آن‌ها جابه‌جا شود مگر اینکه pin شده باشد. برای اجبار به یک پروفایل واحد:

• با auth.order[provider] = ["provider:profileId"] آن را pin کنید، یا
• از بازنویسی هر نشست از طریق /model … همراه با بازنویسی پروفایل استفاده کنید (وقتی سطح UI/چت شما پشتیبانی کند).

# دوره‌های انتظار

وقتی یک پروفایل به‌دلیل خطاهای احراز هویت/rate-limit (یا timeoutی که شبیه rate limiting است) شکست بخورد، OpenClaw آن را در دورهٔ انتظار علامت‌گذاری می‌کند و به پروفایل بعدی می‌رود.

دوره‌های انتظار از backoff نمایی استفاده می‌کنند:

• ۱ دقیقه
• ۵ دقیقه
• ۲۵ دقیقه
• ۱ ساعت (سقف)

وضعیت در auth-state.json زیر usageStats ذخیره می‌شود:

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

# غیرفعال‌سازی‌های billing

خرابی‌های billing/credit (برای مثال "insufficient credits" / "credit balance too low") به‌عنوان شایستهٔ failover در نظر گرفته می‌شوند، اما معمولاً transient نیستند. به‌جای یک دورهٔ انتظار کوتاه، OpenClaw پروفایل را غیرفعال علامت‌گذاری می‌کند (با backoff طولانی‌تر) و به پروفایل/provider بعدی می‌چرخد.

وضعیت در auth-state.json ذخیره می‌شود:

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

پیش‌فرض‌ها:

• backoff مربوط به billing از ۵ ساعت شروع می‌شود، با هر خرابی billing دو برابر می‌شود، و در ۲۴ ساعت سقف می‌خورد.
• اگر پروفایل برای ۲۴ ساعت شکست نخورده باشد، شمارنده‌های backoff reset می‌شوند (قابل پیکربندی).
• retryهای overload پیش از fallback مدل، ۱ چرخش پروفایل در همان provider را مجاز می‌کنند.
• retryهای overload به‌صورت پیش‌فرض از ۰ ms backoff استفاده می‌کنند.

# fallback مدل

اگر همهٔ پروفایل‌های یک provider شکست بخورند، OpenClaw به مدل بعدی در agents.defaults.model.fallbacks می‌رود. این برای خرابی‌های احراز هویت، rate limitها، و timeoutهایی اعمال می‌شود که چرخش پروفایل را تمام کرده‌اند (خطاهای دیگر fallback را جلو نمی‌برند). خطاهای provider که جزئیات کافی ارائه نمی‌کنند همچنان در وضعیت fallback دقیقاً برچسب‌گذاری می‌شوند: empty_response یعنی provider هیچ پیام یا status قابل استفاده‌ای برنگردانده است، no_error_details یعنی provider صراحتاً Unknown error (no error details in response) را برگردانده است، و unclassified یعنی OpenClaw پیش‌نمایش خام را حفظ کرده اما هنوز هیچ classifierی با آن منطبق نشده است.

خطاهای اضافه‌بار و محدودیت نرخ با شدت بیشتری نسبت به cooldownهای صورتحساب مدیریت می‌شوند. به‌طور پیش‌فرض، OpenClaw اجازه می‌دهد یک بار auth-profile همان ارائه‌دهنده دوباره امتحان شود، سپس بدون انتظار به fallback مدل پیکربندی‌شده بعدی جابه‌جا می‌شود. سیگنال‌های مشغول‌بودن ارائه‌دهنده مانند ModelNotReadyException در همان دسته اضافه‌بار قرار می‌گیرند. این رفتار را با auth.cooldowns.overloadedProfileRotations، auth.cooldowns.overloadedBackoffMs و auth.cooldowns.rateLimitedProfileRotations تنظیم کنید.

وقتی یک اجرا از primary پیش‌فرض پیکربندی‌شده، primary یک cron job، primary یک عامل با fallbackهای صریح، یا یک override fallback انتخاب‌شده به‌صورت خودکار شروع می‌شود، OpenClaw می‌تواند زنجیره fallback پیکربندی‌شده مطابق را طی کند. primaryهای عامل بدون fallbackهای صریح و انتخاب‌های صریح کاربر (برای مثال /model ollama/qwen3.5:27b، انتخابگر مدل، sessions.patch، یا overrideهای یک‌باره ارائه‌دهنده/مدل در CLI) سخت‌گیرانه‌اند: اگر آن ارائه‌دهنده/مدل در دسترس نباشد یا پیش از تولید پاسخ شکست بخورد، OpenClaw به‌جای پاسخ‌دادن از یک fallback نامرتبط، شکست را گزارش می‌کند.

# قواعد زنجیره نامزدها

OpenClaw فهرست نامزدها را از provider/model درخواستی فعلی به‌علاوه fallbackهای پیکربندی‌شده می‌سازد.

# کدام خطاها fallback را پیش می‌برند

# رفتار ردکردن cooldown در برابر probe

وقتی همه auth profileهای یک ارائه‌دهنده از قبل در cooldown باشند، OpenClaw به‌طور خودکار آن ارائه‌دهنده را برای همیشه رد نمی‌کند. برای هر نامزد جداگانه تصمیم می‌گیرد:

# overrideهای نشست و جابه‌جایی زنده مدل

تغییرات مدل نشست state مشترک هستند. runner فعال، دستور /model، به‌روزرسانی‌های compaction/session، و reconciliation نشست زنده همگی بخش‌هایی از همان entry نشست را می‌خوانند یا می‌نویسند.

این یعنی retryهای fallback باید با جابه‌جایی زنده مدل هماهنگ شوند:

• فقط تغییرات مدل صریح و کاربرمحور یک جابه‌جایی زنده pending را علامت‌گذاری می‌کنند. این شامل /model، session_status(model=...) و sessions.patch است.
• تغییرات مدل سیستم‌محور مانند چرخش fallback، overrideهای Heartbeat، یا Compaction به‌تنهایی هیچ‌وقت یک جابه‌جایی زنده pending را علامت‌گذاری نمی‌کنند.
• overrideهای مدل کاربرمحور برای سیاست fallback به‌عنوان انتخاب‌های دقیق در نظر گرفته می‌شوند، بنابراین ارائه‌دهنده انتخاب‌شده‌ای که در دسترس نیست به‌جای اینکه توسط agents.defaults.model.fallbacks پنهان شود، به‌صورت شکست نمایش داده می‌شود.
• پیش از شروع retry fallback، reply runner فیلدهای override fallback انتخاب‌شده را در entry نشست persist می‌کند.
• overrideهای fallback خودکار در turnهای بعدی انتخاب‌شده باقی می‌مانند تا OpenClaw در هر پیام یک primary شناخته‌شده خراب را probe نکند. /new، /reset و sessions.reset overrideهای auto-sourced را پاک می‌کنند و نشست را به پیش‌فرض پیکربندی‌شده برمی‌گردانند.
• /status مدل انتخاب‌شده را نشان می‌دهد و وقتی state fallback متفاوت باشد، مدل fallback فعال و دلیل آن را نیز نشان می‌دهد.
• reconciliation نشست زنده overrideهای persistشده نشست را به فیلدهای مدل runtime قدیمی ترجیح می‌دهد.
• اگر خطای live-switch به نامزد بعدی در زنجیره fallback فعال اشاره کند، OpenClaw به‌جای طی‌کردن نامزدهای نامرتبط، مستقیماً به همان مدل انتخاب‌شده می‌پرد.
• اگر تلاش fallback شکست بخورد، runner فقط فیلدهای overrideی را که خودش نوشته rollback می‌کند، و فقط اگر هنوز با همان نامزد شکست‌خورده مطابقت داشته باشند.

این از race کلاسیک جلوگیری می‌کند:

override fallback persistشده این بازه را می‌بندد، و rollback محدود تغییرات دستی یا runtime جدیدتر نشست را دست‌نخورده نگه می‌دارد.

# مشاهده‌پذیری و خلاصه‌های شکست

runWithModelFallback(...) جزئیات هر تلاش را ثبت می‌کند که خوراک logها و پیام‌رسانی cooldown قابل‌نمایش به کاربر می‌شود:

• ارائه‌دهنده/مدل امتحان‌شده
• دلیل (rate_limit، overloaded، billing، auth، model_not_found، و دلایل مشابه failover)
• status/code اختیاری
• خلاصه خطای خوانا برای انسان

logهای ساختاریافته model_fallback_decision همچنین وقتی یک نامزد شکست می‌خورد، رد می‌شود، یا fallback بعدی موفق می‌شود، فیلدهای flat fallbackStep* را شامل می‌شوند. این فیلدها گذار تلاش‌شده را صریح می‌کنند (fallbackStepFromModel، fallbackStepToModel، fallbackStepFromFailureReason، fallbackStepFromFailureDetail، fallbackStepFinalOutcome) تا صادرکننده‌های log و diagnostic بتوانند شکست primary را بازسازی کنند، حتی وقتی fallback نهایی هم شکست بخورد.

وقتی همه نامزدها شکست بخورند، OpenClaw خطای FallbackSummaryError را throw می‌کند. reply runner بیرونی می‌تواند از آن برای ساختن پیامی مشخص‌تر مانند «همه مدل‌ها به‌طور موقت rate-limited هستند» استفاده کند و اگر نزدیک‌ترین زمان انقضای cooldown معلوم باشد، آن را اضافه کند.

آن خلاصه cooldown از مدل آگاه است:

• محدودیت‌های نرخ model-scoped نامرتبط برای زنجیره ارائه‌دهنده/مدل امتحان‌شده نادیده گرفته می‌شوند
• اگر block باقی‌مانده یک محدودیت نرخ model-scoped مطابق باشد، OpenClaw آخرین expiry مطابقی را گزارش می‌کند که هنوز آن مدل را block می‌کند

# پیکربندی مرتبط

برای موارد زیر، پیکربندی Gateway را ببینید:

• 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
• routing مربوط به agents.defaults.imageModel

برای نمای کلی گسترده‌تر انتخاب مدل و fallback، مدل‌ها را ببینید.