انتقال اضطراری مدل

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: [] استفاده کنید، یا برای فعال‌کردن جایگزینی مدل برای آن عامل، فهرستی غیرخالی ارائه دهید.
• Override جایگزین خودکار: یک جایگزین زمان اجرا پیش از تلاش دوباره، providerOverride، modelOverride، modelOverrideSource: "auto"، و مدل مبدأ انتخاب‌شده را می‌نویسد. آن override خودکار می‌تواند بدون آزمودن مدل اصلی در هر پیام، زنجیرهٔ جایگزین پیکربندی‌شده را ادامه دهد، اما OpenClaw هر از گاهی مبدأ پیکربندی‌شده را دوباره می‌آزماید و وقتی بازیابی شد override خودکار را پاک می‌کند. /new، /reset، و sessions.reset نیز overrideهای با منبع خودکار را پاک می‌کنند. اجراهای Heartbeat بدون heartbeat.model صریح، وقتی مبدأشان دیگر با پیش‌فرض پیکربندی‌شدهٔ فعلی تطابق ندارد، overrideهای خودکار مستقیم را پاک می‌کنند.
• Override نشست کاربر: /model، انتخاب‌گر مدل، session_status(model=...)، و sessions.patch مقدار modelOverrideSource: "user" را می‌نویسند. این یک انتخاب دقیق نشست است. اگر ارائه‌دهنده/مدل انتخاب‌شده پیش از تولید پاسخ شکست بخورد، OpenClaw به‌جای پاسخ‌دادن از یک جایگزین پیکربندی‌شدهٔ نامرتبط، خرابی را گزارش می‌کند.
• Override نشست قدیمی: ورودی‌های نشست قدیمی‌تر ممکن است modelOverride را بدون modelOverrideSource داشته باشند. OpenClaw این موارد را override کاربر در نظر می‌گیرد تا یک انتخاب صریح قدیمی بی‌سروصدا به رفتار جایگزینی تبدیل نشود.
• مدل payload مربوط به Cron: مقدار payload.model / --model در یک کار cron مدل اصلی همان کار است، نه override نشست کاربر. مگر این‌که کار payload.fallbacks را ارائه کند، از جایگزین‌های پیکربندی‌شده استفاده می‌کند؛ payload.fallbacks: [] اجرای cron را سخت‌گیرانه می‌کند.

فاصلهٔ آزمون مدل اصلی در جایگزینی خودکار پنج دقیقه است و قابل پیکربندی نیست. OpenClaw آزمون‌های اخیر را به‌ازای هر نشست و مدل اصلی به خاطر می‌سپارد تا مدل اصلیِ در حال شکست در هر نوبت دوباره امتحان نشود. OpenClaw وقتی یک نشست به جایگزین می‌رود یک اعلان قابل مشاهده می‌فرستد و وقتی به مدل اصلی انتخاب‌شده برمی‌گردد اعلان دیگری می‌فرستد؛ این اعلان را در هر نوبتِ جایگزین چسبنده تکرار نمی‌کند.

کش پرش از خرابی احراز هویت

به‌طور پیش‌فرض، هر نوبت جدید رفتار موجود تلاش دوبارهٔ جایگزین را حفظ می‌کند: OpenClaw هر نامزد جایگزین پیکربندی‌شده را دوباره امتحان می‌کند، از جمله نامزدهای غیر اصلی که اخیراً با auth یا auth_permanent شکست خورده‌اند.

اپراتورهایی که ترجیح می‌دهند این خرابی‌های تکراری احراز هویت را سرکوب کنند می‌توانند با این گزینه فعالش کنند:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

وقتی فعال باشد، OpenClaw پس از یک خرابی از کلاس احراز هویت، برای یک نامزد جایگزین غیر اصلی، یک نشانگر پرش درون‌حافظه‌ای و محدود به نشست ثبت می‌کند. این نشانگر بر اساس شناسهٔ نشست، ارائه‌دهنده، و مدل کلیدگذاری می‌شود. نامزدهای اصلی هرگز پرش نمی‌شوند، بنابراین یک انتخاب صریح مدل کاربر همچنان خطای واقعی احراز هویت را نشان می‌دهد. این کش محلیِ فرایند است و با راه‌اندازی دوبارهٔ Gateway پاک می‌شود.

مقدار آن یک TTL بر حسب میلی‌ثانیه است. 0 یا مقدار تنظیم‌نشده کش را غیرفعال می‌کند. مقادیر مثبت بین ۱ ثانیه و ۱۰ دقیقه محدود می‌شوند.

اعلان‌های جایگزینی قابل مشاهده برای کاربر

وقتی یک نشست به جایگزین خودکار انتخاب‌شده می‌رود، OpenClaw یک اعلان وضعیت در همان سطح پاسخ می‌فرستد:

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

وقتی آزمون بعدی موفق شود و نشست به مدل اصلی انتخاب‌شده برگردد، OpenClaw می‌فرستد:

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

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

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

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

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

جزئیات بیشتر: 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-agent.sqlite هر عامل قرار دارند.

ترتیب چرخش

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

خنک‌سازی‌ها از عقب‌نشینی نمایی استفاده می‌کنند:

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

وضعیت در وضعیت احراز هویت SQLite هر عامل، زیر usageStats ذخیره می‌شود:

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

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

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

وضعیت در وضعیت احراز هویت SQLite هر عامل ذخیره می‌شود:

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

پیش‌فرض‌ها:

• عقب‌نشینی صورتحساب از ۵ ساعت شروع می‌شود، به‌ازای هر خطای صورتحساب دو برابر می‌شود، و در ۲۴ ساعت سقف می‌خورد.
• شمارنده‌های عقب‌نشینی اگر پروفایل به‌مدت ۲۴ ساعت ناموفق نشده باشد، بازنشانی می‌شوند (قابل پیکربندی).
• تلاش‌های مجددِ بارگذاری‌شده اجازه ۱ چرخش پروفایل همان ارائه‌دهنده را پیش از جایگزینی مدل می‌دهند.
• تلاش‌های مجددِ بارگذاری‌شده به‌طور پیش‌فرض از ۰ میلی‌ثانیه عقب‌نشینی استفاده می‌کنند.

جایگزینی مدل

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

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

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

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

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

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

رفتار پرش از خنک‌سازی در برابر کاوش

وقتی همه پروفایل‌های احراز هویت یک ارائه‌دهنده از قبل در خنک‌سازی هستند، OpenClaw آن ارائه‌دهنده را به‌طور خودکار برای همیشه رد نمی‌کند. برای هر نامزد جداگانه تصمیم می‌گیرد:

بازنویسی‌های نشست و تعویض زنده مدل

تغییرات مدل نشست وضعیت مشترک هستند. اجراکننده فعال، فرمان /model، به‌روزرسانی‌های Compaction/نشست، و سازگارسازی نشست زنده همگی بخش‌هایی از همان ورودی نشست را می‌خوانند یا می‌نویسند.

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

• فقط تغییرات مدلِ صریح و کاربرمحور یک تعویض زنده در انتظار را علامت می‌زنند. این شامل /model، session_status(model=...)، و sessions.patch است.
• تغییرات مدلِ سیستم‌محور مانند چرخش جایگزین، بازنویسی‌های Heartbeat، یا Compaction به‌تنهایی هرگز یک تعویض زنده در انتظار را علامت نمی‌زنند.
• بازنویسی‌های مدل کاربرمحور برای سیاست جایگزینی به‌عنوان انتخاب‌های دقیق تلقی می‌شوند، بنابراین یک ارائه‌دهنده انتخاب‌شده دسترس‌ناپذیر به‌جای اینکه با agents.defaults.model.fallbacks پوشانده شود، به‌صورت خطا آشکار می‌شود.
• پیش از شروع یک تلاش مجدد جایگزینی، اجراکننده پاسخ فیلدهای بازنویسی جایگزین انتخاب‌شده را در ورودی نشست پایدار می‌کند.
• بازنویسی‌های جایگزین خودکار در نوبت‌های بعدی منتخب باقی می‌مانند تا OpenClaw در هر پیام یک اصلیِ شناخته‌شده نامناسب را کاوش نکند. OpenClaw به‌صورت دوره‌ای مبدا پیکربندی‌شده را دوباره کاوش می‌کند و وقتی بازیابی شد بازنویسی خودکار را پاک می‌کند؛ /new، /reset، و sessions.reset بازنویسی‌های منبع‌گرفته از خودکار را بلافاصله پاک می‌کنند.
• پاسخ‌های کاربر گذارهای جایگزینی و بازیابیِ پاک‌شدن جایگزین را یک‌بار برای هر تغییر وضعیت اعلام می‌کنند. نوبت‌های جایگزین چسبنده اعلان را تکرار نمی‌کنند.
• /status مدل انتخاب‌شده را نشان می‌دهد و، وقتی وضعیت جایگزینی متفاوت باشد، مدل جایگزین فعال و دلیل را نیز نشان می‌دهد.
• سازگارسازی نشست زنده بازنویسی‌های پایدارشده نشست را به فیلدهای مدل زمان‌اجرای قدیمی ترجیح می‌دهد.
• اگر خطای تعویض زنده به نامزد بعدی در زنجیره جایگزین فعال اشاره کند، OpenClaw به‌جای طی‌کردن نامزدهای نامرتبط، مستقیم به همان مدل انتخاب‌شده می‌پرد.
• اگر تلاش جایگزینی ناموفق شود، اجراکننده فقط فیلدهای بازنویسی‌ای را که خودش نوشته است برمی‌گرداند، و فقط اگر هنوز با همان نامزد ناموفق مطابقت داشته باشند.

این از رقابت کلاسیک جلوگیری می‌کند:

بازنویسی جایگزین پایدارشده آن پنجره را می‌بندد، و بازگردانی محدود تغییرات دستی یا زمان‌اجرای جدیدتر نشست را دست‌نخورده نگه می‌دارد.

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

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

• ارائه‌دهنده/مدل امتحان‌شده
• دلیل (rate_limit، overloaded، billing، auth، model_not_found، و دلایل جایگزینی مشابه)
• وضعیت/کد اختیاری
• خلاصه خطای خوانا برای انسان

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

وقتی همه نامزدها ناموفق شوند، OpenClaw خطای FallbackSummaryError را پرتاب می‌کند. اجراکننده پاسخ بیرونی می‌تواند از آن برای ساختن پیامی مشخص‌تر مانند "all models are temporarily rate-limited" استفاده کند و نزدیک‌ترین انقضای خنک‌سازی را وقتی معلوم باشد شامل کند.

آن خلاصه خنک‌سازی آگاه از مدل است:

• محدودیت‌های نرخ محدود به مدلِ نامرتبط برای زنجیره ارائه‌دهنده/مدل امتحان‌شده نادیده گرفته می‌شوند
• اگر مسدودیت باقی‌مانده یک محدودیت نرخ محدود به مدلِ منطبق باشد، OpenClaw آخرین انقضای منطبقی را که هنوز آن مدل را مسدود می‌کند گزارش می‌دهد

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

برای موارد زیر پیکربندی 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، مدل‌ها را ببینید.