بازیابی پس از راه‌اندازی مجدد

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

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

چه چیزهایی پس از راه‌اندازی مجدد باقی می‌مانند

راه‌اندازی‌های مجدد کنترل‌شده ابتدا منتظر تخلیه می‌مانند

یک راه‌اندازی مجدد درخواستی (openclaw gateway restart، تغییری در پیکربندی که به راه‌اندازی مجدد نیاز دارد، یا به‌روزرسانی Gateway) کارهای در حال اجرا را بلافاصله متوقف نمی‌کند. Gateway پذیرش کار جدید را متوقف می‌کند، سپس تا سقف مهلت تخلیه (به‌طور پیش‌فرض 5 دقیقه) منتظر می‌ماند نوبت‌های فعال عامل و وظایف پس‌زمینه پایان یابند. بنابراین بیشتر راه‌اندازی‌های مجدد هیچ کاری را قطع نمی‌کنند.

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

کارِ قطع‌شده چگونه شناسایی می‌شود

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

• هنگام پذیرش نوبت: برای یک نوبت متنی معمولی در یک نشست اصلی موجود، Gateway پیش از اجرای مدل یا هوک before_agent_reply، پیام کاربر را اضافه می‌کند، نشست را در حال اجرا علامت می‌زند و ادعای تحویل بازیابی آن را در یک تراکنش SQLite ثبت می‌کند. Control UI این کار را پیش از بازگرداندن تأییدیه started انجام می‌دهد؛ ارسال کانال نیز وقتی نوبت آماده‌شده اجرای عامل را می‌پذیرد، این کار را انجام می‌دهد. فرمان‌ها، پیوست‌ها، جایگزینی‌های مختص هر نوبت، تحویل‌های معلق، نشانه‌های توقف قبلی، نشست‌های تحت مالکیت Plugin و نوبت‌های دارای هوک اجرایی، مسیرهای پذیرش تخصصی خود را حفظ می‌کنند. اگر هوک before_agent_reply نصب شده باشد، پذیرش مرحله آن را نیز ثبت می‌کند. بازیابی هرگز هوکی را که در میانه فراخوانی قطع شده است دوباره اجرا نمی‌کند. پس از پایان یک هوک مدیریت‌نشده، نقطه وارسی آن نتیجه را ثبت می‌کند، اما تا زمانی که آن هوک فعال است، بازیابی همچنان به‌صورت ایمن با شکست متوقف می‌شود: نقطه وارسی نمی‌تواند ثابت کند که همان کد و پیکربندی Plugin پس از راه‌اندازی مجدد بارگذاری شده‌اند. نتایج متنی مدیریت‌شده و نتایج بی‌صدا برای تعیین تکلیف قطعی به‌طور جداگانه نقطه‌گذاری می‌شوند. ادعاهای بازیابی پایدار که نسخه‌های قدیمی‌تر نوشته‌اند، نشانگر مالکیت منبع ندارند؛ بنابراین هنگام ارتقا نیز همان بررسی ایمنِ هوک را دریافت می‌کنند.
• هنگام خاموش‌شدن: در طول تخلیه راه‌اندازی مجدد، هر نشستی که اجرای فعالی دارد، پیش از توقف اجرا با یک نشانگر بازیابی در مخزن نشست علامت‌گذاری می‌شود.
• هنگام راه‌اندازی: Gateway مخازن نشست را برای یافتن نشست‌هایی پویش می‌کند که هنوز ادعا می‌کنند در حال اجرا هستند، اما در فرایند جدید مالک زنده‌ای ندارند. این کار خرابی‌ها و توقف‌های سختی را که در آن‌ها هیچ کد خاموش‌سازی اجرا نشده است شناسایی می‌کند. فایل‌های قفل قدیمی رونوشت نیز هم‌زمان پاک‌سازی می‌شوند.

ازسرگیری خودکار

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

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

پس از پایان بودجه پایدار، نشست به‌جای ورود به حلقه بی‌پایان، با سنگ‌قبر علامت‌گذاری می‌شود. نشست ناموفق را بررسی کنید و برای آغاز یک جایگزین از /new یا /reset استفاده کنید. openclaw doctor --fix می‌تواند پرچم توقف قدیمی را که با سنگ‌قبر تعارض دارد اصلاح کند، اما آن چرخه بازیابی را دوباره فعال نمی‌کند.

هر تلاش مجدد از یک شناسه ارسال پایدار استفاده می‌کند؛ بنابراین شکست مبهم اتصال نمی‌تواند یک بازیابی را دو بار آغاز کند. نوبت‌های تکمیل‌شده و غیرقابل‌ازسرگیری Control UI نیز سنگ‌قبرهای پایدار و محدود برای هم‌توانی را حفظ می‌کنند تا صندوق خروجیِ در حال اتصال مجدد بتواند بدون اجرای دوباره درخواست، آن‌ها را کنار بگذارد.

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

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

پیش از ازسرگیری، Gateway بررسی می‌کند که ادامه‌دادن از انتهای رونوشت ایمن باشد. اگر چنین نباشد (برای مثال، نوبت با یک تأیید معلق قدیمی پایان یافته باشد)، نشست کورکورانه دوباره اجرا نمی‌شود؛ در عوض عامل اعلان کوتاهی منتشر می‌کند و از کاربر می‌خواهد آخرین درخواست را دوباره ارسال کند. برای WebChat، آن اعلان مستقیماً در تاریخچه نشست نوشته می‌شود تا پس از اتصال مجدد قابل مشاهده بماند.

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

زیرعامل‌ها

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

• اجراهایی که بیش از 2 ساعت پیش قطع شده‌اند، به‌جای ازسرگیری نهایی می‌شوند تا Gateway که در طول شب از دسترس خارج بوده است، کارهای قدیمی را دوباره زنده نکند.
• نشستی که مکرراً در بازیابی شکست می‌خورد، به‌عنوان گیرکرده با سنگ‌قبر علامت‌گذاری می‌شود تا بازیابی نتواند برای همیشه تکرار شود.

وظایف پس‌زمینه

رجیستری وظایف پس‌زمینه بر پایه SQLite است و هنگام راه‌اندازی و در بازه‌های دوره‌ای تطبیق داده می‌شود: نتایج پایدار ثبت‌شده توسط اجراهای پایان‌یافته بازیابی می‌شوند و اجراهایی که فرایند مالکشان ناپدید شده است، پس از یک مهلت به‌جای معلق‌ماندن همیشگی، گم‌شده علامت‌گذاری می‌شوند.

راه‌اندازی‌های مجدد درخواستی عامل

وقتی خود عامل راه‌اندازی مجدد را فعال می‌کند (برای اعمال تغییر پیکربندی، به‌روزرسانی Gateway یا درخواست صریح راه‌اندازی مجدد)، پیش از خروج فرایند، یک نشانگر راه‌اندازی مجدد در SQLite نوشته می‌شود. پس از راه‌اندازی، Gateway نتیجه را به گفت‌وگوی مبدأ ارسال و یک نوبت ادامه یک‌باره را فعال می‌کند تا عامل دقیقاً از همان نقطه‌ای که متوقف شده بود، در همان کانال و رشته، ادامه دهد.

ستون‌های نوع‌دار SQLite نشانگر، مرجع معتبر مدیریت راه‌اندازی مجدد هستند؛ مقدار payload_json آن فقط یک سایه برای اجرای مجدد/اشکال‌زدایی است. زمان اجرا وضعیت SQLite را بدون مسیر جایگزین فایل می‌خواند، می‌نویسد و پاک می‌کند. در طول انتقال محل ذخیره‌سازی، یک مهاجرت وضعیت محدود هنگام راه‌اندازی و از طریق Doctor اجرا می‌شود تا restart-sentinel.json اعتبارسنجی‌شده‌ای را که فرایند قدیمی‌تر پس از به‌روزرسانی باقی گذاشته است حفظ کند. مهاجرت، ردیف نوع‌دار را تأیید و فایل مبدأ را حذف می‌کند، سپس مدیریت عادی راه‌اندازی مجدد ادامه می‌یابد.

سازوکارهای ایمنی و مشاهده‌پذیری

• قطع‌کننده حلقه خرابی: 3 راه‌اندازی ناپاک در مدت 5 دقیقه، قطع‌کننده‌ای را فعال می‌کند که شروع خودکار سرویس‌های جانبی را در راه‌اندازی بعدی متوقف می‌کند تا Gateway در حال خرابی، خرابی خود را تشدید نکند. پس از پایان بازه راه‌اندازی‌های ناپاک، به حالت عادی بازمی‌گردد.
• بودجه تلاش نشست اصلی: سه تلاش خودکارِ محاسبه‌شده برای ارسال در هر چرخه قطع‌شده؛ پایان بودجه، آن نشست را تا زمان بررسی و جایگزینی با سنگ‌قبر علامت‌گذاری می‌کند.
• معیارها: فعالیت بازیابی از طریق Prometheus با نام‌های openclaw_session_recovery_total و openclaw_session_recovery_age_seconds صادر می‌شود.
• گزارش‌ها: تصمیم‌های بازیابی در زیرسامانه‌های main-session-restart-recovery و subagent-interrupted-resume ثبت می‌شوند.

چه چیزهایی از سر گرفته نمی‌شوند

• نشست‌هایی که از بازیابی نشست اصلی مستثنا هستند، زیرا مالک دیگری از قبل آن‌ها را مدیریت می‌کند: نشست‌های زیرعامل (بازیابی زیرعامل)، نشست‌های cron (زمان‌بند طبق برنامه دوباره اجرا می‌کند) و نشست‌های تحت مدیریت ACP (IDE یا کلاینت متصل مالک ازسرگیری است).
• نشست‌هایی که نمی‌توان با ایمنی از انتهای رونوشت آن‌ها ادامه داد؛ این نشست‌ها به‌جای اجرای مجدد بی‌صدا، اعلان ارسال مجدد توضیح‌داده‌شده در بالا را دریافت می‌کنند.
• کاری که هرگز پذیرفته نشده است: پیام‌هایی که در بازه تخلیه می‌رسند، به‌جای آنکه بی‌صدا در صف یک فرایند در حال پایان قرار گیرند، با خطای صریح راه‌اندازی مجدد رد می‌شوند.
• نوبت‌های تعبیه‌شده مستقل نمی‌توانند کنترل نشست اصلی دارای بازیابی معلق راه‌اندازی مجدد را به‌دست گیرند، زیرا مالک چرخه عمر مشترکی با Gateway ندارند. نوبت را از طریق Gateway اجرا کنید یا آن را در همان‌جا با /new یا /reset بازنشانی کنید.