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

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

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

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

این عمداً محدودتر از «ذخیره و بازیابی کل نشست» است. اجراکننده پاسخ فقط فیلدهای انتخاب مدل متعلق به خود برای جایگزینی را ماندگار می‌کند: providerOverride، modelOverride، modelOverrideSource، authProfileOverride، authProfileOverrideSource، authProfileOverrideCompactionCount. این کار مانع می‌شود تلاش مجدد ناموفق یک مدل جایگزین، تغییرات جدیدتر و نامرتبط نشست را بازنویسی کند؛ مانند تغییر دستی /model یا به‌روزرسانی چرخش نشست که هنگام اجرای تلاش رخ داده است.

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

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

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

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

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

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

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

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

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

مقدار، مدت اعتبار بر حسب میلی‌ثانیه است. مقدار 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 که فقط برای واردکردن استفاده می‌شود: ~/.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).
• کلید فرعی: 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 آن را در دوره انتظار قرار می‌دهد و به پروفایل بعدی می‌رود.

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

• خطای اول: ۳۰ ثانیه
• خطای دوم: ۱ دقیقه
• خطای سوم و بیشتر: ۵ دقیقه (سقف)

پس از پایان بازه خطای نمایه (auth.cooldowns.failureWindowHours، پیش‌فرض ۲۴)، شمارنده‌ها بازنشانی می‌شوند.

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

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

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

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

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

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

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

مقادیر پیش‌فرض (auth.cooldowns.*):

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

مدل جایگزین

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

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

وقتی یک اجرا از مدل اصلی پیش‌فرض پیکربندی‌شده، مدل اصلی یک کار 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 را پرتاب می‌کند. اجراکنندهٔ بیرونی پاسخ می‌تواند از آن برای ساخت پیامی مشخص‌تر، مانند «همهٔ مدل‌ها موقتاً با محدودیت نرخ مواجه‌اند»، استفاده کند و در صورت مشخص‌بودن نزدیک‌ترین زمان پایان دورهٔ انتظار، آن را نیز درج کند.

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

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

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

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

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• مسیریابی agents.defaults.imageModel

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