جایگزینی خودکار مدل

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

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

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

اجرای جایگزین به نوبت جاری محدود است. اجراکننده پاسخ فقط وضعیت اعلان جایگزین را ماندگار می‌کند تا /status و اعلان‌های انتقال بتوانند مدل انتخاب‌شده را از مدلی که پاسخ داده است متمایز کنند؛ جایگزین را به‌عنوان انتخاب مدل نوبت بعدی ماندگار نمی‌کند.

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

منبع انتخاب تعیین می‌کند که آیا زنجیره جایگزین مجاز است:

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

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

حافظه نهان پرش از خرابی احراز هویت

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

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

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

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

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

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

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

↪️ مدل جایگزین: <fallback> (انتخاب‌شده <primary>؛ <reason>)

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

↪️ مدل جایگزین پاک شد: <primary> (قبلاً <fallback>)

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

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

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

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

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

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

• type: "api_key" ← { provider, key }
• type: "oauth" ← { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl برای برخی ارائه‌دهندگان)
• type: "token" ← توکن ثابت از نوع bearer با امکان انقضا؛ OpenClaw آن را تازه‌سازی نمی‌کند (برای aws-sdk و دیگر حالت‌های احراز هویت زنجیره اعتبارنامه استفاده می‌شود)

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

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

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

پروفایل‌ها در مخزن پروفایل احراز هویت openclaw-agent.sqlite هر عامل قرار دارند.

ترتیب چرخش

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

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

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

چسبندگی نشست (سازگار با حافظه نهان)

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

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

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

اشتراک 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 نگه می‌دارد. پس از گذشت زمان بازنشانی، پروفایل اشتراک دوباره واجد شرایط می‌شود و انتخاب خودکار بعدی می‌تواند به آن بازگردد.

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

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

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

دوره‌های توقف عادی (غیر از صورت‌حساب و احراز هویت دائمی) بر اساس تعداد خطاهای اخیر پروفایل افزایش می‌یابند:

• خطای اول: 30 ثانیه
• خطای دوم: 1 دقیقه
• خطای سوم و بیشتر: 5 دقیقه (سقف)

پس از سپری‌شدن بازهٔ داخلی خطای پروفایل، شمارنده‌ها بازنشانی می‌شوند.

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

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

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

خطاهای صورت‌حساب/اعتبار (برای مثال «اعتبار کافی نیست» / «موجودی اعتبار بسیار کم است») شایستهٔ failover تلقی می‌شوند، اما معمولاً گذرا نیستند. OpenClaw به‌جای یک دورهٔ توقف کوتاه، پروفایل را غیرفعال علامت‌گذاری می‌کند (با پس‌روی طولانی‌تر) و به پروفایل/ارائه‌دهندهٔ بعدی می‌چرخد.

خطاهای دائمی احراز هویت با اطمینان بالا (کلیدهای لغوشده/غیرفعال‌شده و فضاهای کاری غیرفعال‌شده) وارد مسیر غیرفعال‌سازی مشابهی می‌شوند، اما بسیار زودتر از خطاهای صورت‌حساب بازیابی می‌شوند، زیرا برخی ارائه‌دهندگان هنگام رخداد اختلال، محتوایی با ظاهر خطای احراز هویت را به‌صورت گذرا نمایش می‌دهند.

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

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

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

fallback مدل

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

نشانه‌های مشغول‌بودن ارائه‌دهنده مانند ModelNotReadyException در دستهٔ ازدحام قرار می‌گیرند و از همان سیاست یک چرخش و سپس fallback مربوط به محدودیت نرخ پیروی می‌کنند (جدول پیش‌فرض‌های بالا را ببینید).

اگر کل زنجیرهٔ نامزدها صرفاً به‌دلیل خطاهای ازدحام تمام شود، اجراکنندهٔ پاسخ زنجیره را در همان نوبت تا 10 بار دوباره امتحان می‌کند. تلاش مجدد کل نوبت فقط پیش از آغاز اجرای ابزار یا خروجی دستیار مجاز است؛ بنابراین اگر ازدحام پس از کار قابل‌مشاهده رخ دهد، از تغییرات یا پیام‌های تکراری جلوگیری می‌شود. پس‌روی از 2.5 ثانیه آغاز می‌شود و تا سقف 30 ثانیه دو برابر می‌شود. هنگامی که نوبت 30 ثانیه در انتظار بوده باشد، OpenClaw یک اعلان وضعیت گذرا ارسال می‌کند: The AI service is temporarily overloaded. I’m still retrying; this may take a few minutes. تلاش مجدد و هر برندهٔ fallback فقط به همان نوبت محدود می‌مانند؛ خطاهای گذرای عادی سرور سیاست جداگانهٔ یک تلاش مجدد خود را حفظ می‌کنند.

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

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

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

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

رفتار ردکردن دورهٔ توقف در برابر کاوش

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

overrideهای نشست و تعویض زندهٔ مدل

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

تعویض زندهٔ مدل از این قواعد پیروی می‌کند:

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

اجرای فعال نامزد انتخاب‌شدهٔ خود را مستقیماً حمل می‌کند. تطبیق زنده فقط برای یک تعویض صریح در انتظار از سوی کاربر، آن نامزد را تغییر می‌دهد؛ بنابراین هیچ override موقت fallback یا بازگردانی لازم نیست.

مشاهده‌پذیری و خلاصه‌های خطا

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

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

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

وقتی همه نامزدها ناموفق باشند، OpenClaw خطای FallbackSummaryError را ایجاد می‌کند. اجراکننده بیرونی پاسخ می‌تواند از آن برای ساختن پیامی مشخص‌تر، مانند «نرخ درخواست همه مدل‌ها موقتاً محدود شده است»، استفاده کند و در صورت مشخص‌بودن نزدیک‌ترین زمان پایان دوره انتظار، آن را نیز درج کند.

این خلاصه دوره انتظار، مدل را در نظر می‌گیرد:

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

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

برای موارد زیر به پیکربندی Gateway مراجعه کنید:

• auth.profiles / auth.order
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• مسیریابی agents.defaults.imageModel

برای نمای کلی گسترده‌ترِ انتخاب مدل و بازگشت به گزینه جایگزین، به مدل‌ها مراجعه کنید.