جایگزینی مدل هنگام خرابی

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

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

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

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

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

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

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

این کار مانع می‌شود تلاش دوباره ناموفقِ بازگشت، تغییرات نامرتبط جدیدتر نشست را بازنویسی کند؛ مثل تغییرهای دستی /model یا به‌روزرسانی‌های چرخش نشست که هنگام اجرای تلاش رخ داده‌اند.

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

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

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

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

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

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

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

انواع اعتبارنامه:

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

شناسه‌های نمایه

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

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

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

ترتیب چرخش

وقتی یک ارائه‌دهنده چند نمایه دارد، OpenClaw ترتیبی مثل این انتخاب می‌کند:

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

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

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

OpenClaw نمایه احراز هویت انتخاب‌شده را برای هر نشست ثابت می‌کند تا کش‌های ارائه‌دهنده گرم بمانند. در هر درخواست چرخش انجام نمی‌دهد. نمایه ثابت‌شده دوباره استفاده می‌شود تا وقتی که:

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

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

اشتراک OpenAI Codex به‌همراه پشتیبان کلید API

برای مدل‌های عامل OpenAI، احراز هویت و زمان اجرا جدا هستند. openai/gpt-* روی harness Codex می‌ماند، در حالی که احراز هویت می‌تواند بین یک نمایه اشتراک Codex و یک پشتیبان کلید API OpenAI بچرخد.

برای ترتیب قابل مشاهده برای کاربر از auth.order.openai استفاده کنید:

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

نمایه‌های موجود اشتراک Codex ممکن است همچنان از شناسه نمایه قدیمی openai-codex:* استفاده کنند. پشتیبان کلید API مرتب‌شده می‌تواند یک نمایه کلید API معمولی openai:* باشد. وقتی اشتراک به محدودیت مصرف Codex می‌رسد، OpenClaw زمان دقیق بازنشانی را، اگر Codex ارائه کند، ثبت می‌کند، نمایه احراز هویت مرتب‌شده بعدی را امتحان می‌کند، و اجرا را داخل harness Codex نگه می‌دارد. پس از عبور زمان بازنشانی، نمایه اشتراک دوباره واجد شرایط است و انتخاب خودکار بعدی می‌تواند به آن برگردد.

فقط وقتی از نمایه ثابت‌شده توسط کاربر استفاده کنید که می‌خواهید یک حساب/کلید را برای آن نشست اجبار کنید. نمایه‌های ثابت‌شده توسط کاربر عمداً سخت‌گیرانه هستند و بی‌سروصدا به نمایه دیگری نمی‌پرند.

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

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

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

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

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

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

غیرفعال‌سازی‌های صورت‌حساب

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

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

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

پیش‌فرض‌ها:

• backoff مربوط به صورت‌حساب از 5 ساعت شروع می‌شود، با هر شکست صورت‌حساب دو برابر می‌شود، و در 24 ساعت سقف دارد.
• اگر profile برای 24 ساعت شکست نخورده باشد، شمارنده‌های backoff بازنشانی می‌شوند (قابل پیکربندی).
• تلاش‌های دوباره برای حالت overloaded اجازه 1 چرخش profile در همان provider را پیش از model fallback می‌دهند.
• تلاش‌های دوباره برای حالت overloaded به‌طور پیش‌فرض از 0 ms backoff استفاده می‌کنند.

Model fallback

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

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

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

قواعد زنجیره candidate

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

کدام خطاها fallback را جلو می‌برند

رفتار عبور از cooldown در برابر probe

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

overrideهای session و live model switching

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

این یعنی retryهای fallback باید با live model switching هماهنگ شوند:

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

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

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

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

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

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

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

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

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

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

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

برای موارد زیر پیکربندی 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
• مسیریابی agents.defaults.imageModel

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