طرح‌واره‌های پایگاه داده

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

چیدمان پایگاه داده

چند قابلیت با حجم بالا یا چرخه عمر خاص، از ذخیره‌گاه‌های اختصاصی SQLite استفاده می‌کنند؛ از جمله رجیستری وظایف و داده‌های مسیر حرکت.

قرارداد نسخه‌بندی

هر پایگاه داده، طرح‌واره خود را در دو محل ثبت می‌کند:

• PRAGMA user_version نسخه طرح‌واره SQLite است.
• ردیف اصلی schema_meta مقادیر role، agent_id، schema_version و app_version را ثبت می‌کند. app_version نسخه OpenClaw است که آخرین بار فراداده طرح‌واره را نوشته است.

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

نصب دستی OpenClaw از طریق npm، محافظ به‌روزرسان را دور می‌زند. بررسی‌های باز شدن پایگاه داده همچنان نسخه ناسازگار را نمی‌پذیرند.

تاریخچه طرح‌واره عامل

نسخه 3 یک مرحله توسعه منتشرنشده بود که در نسخه 4 ادغام شد.

تاریخچه طرح‌واره وضعیت

بررسی‌های یکپارچگی

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

عیب‌یابی

چرا پس از به‌روزرسانی به 2026.7.2 نمی‌توان به عقب بازگشت

همه انتشارها تا v2026.7.1 از طرح‌واره عامل 1 و طرح‌واره وضعیت 1 استفاده می‌کردند. رشته انتشار 2026.7.2 (از v2026.7.2-beta.1 به بعد) پایگاه‌های داده را در نخستین راه‌اندازی به جلو مهاجرت می‌دهد. این مهاجرت یک‌طرفه است: داده‌ها در طرح‌واره جدیدتر بازنویسی می‌شوند و نصب نسخه قدیمی‌تر OpenClaw پس از آن، این فرایند را معکوس نمی‌کند. نسخه قدیمی‌تر با خطای newer schema version که نسخه مالک پایگاه داده را مشخص می‌کند، از راه‌اندازی خودداری می‌کند.

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

1. یک نسخه پشتیبان تهیه‌شده پیش از به‌روزرسانی را بازیابی کنید. پیش از به‌روزرسانی‌های عمده، نسخه‌های پشتیبان را ایجاد و اعتبارسنجی کنید.
2. نسخه قدیمی‌تر را با یک پوشه وضعیت جداگانه (OPENCLAW_STATE_DIR) اجرا کنید. این نسخه از ابتدا شروع می‌کند؛ داده‌های مهاجرت‌یافته برای زمانی که به نسخه جدیدتر بازگردید، دست‌نخورده باقی می‌مانند.
3. رویه تنزل نسخه دستی زیر را دنبال کنید. این روش پشتیبانی نمی‌شود و بدون یک نسخه پشتیبان اعتبارسنجی‌شده، خطر از دست رفتن داده‌ها را دارد.

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

Gateway به‌دلیل خطای نسخه جدیدتر طرح‌واره از راه‌اندازی خودداری می‌کند

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

پس از ناموفق بودن اعتبارسنجی یکپارچگی، یک پایگاه داده قرنطینه شده است

اعتبارسنج پس‌زمینه ثابت کرده است که فایل خراب است و اکنون هر بار باز شدن، به‌جای اسکن مجدد فوراً شکست می‌خورد. پایگاه داده را از نسخه پشتیبان بازیابی یا آن را تعمیر کنید، سپس برای پاک کردن سابقه قرنطینه، openclaw doctor --fix را اجرا کنید. اگر خود سابقه قرنطینه قابل پاک شدن نباشد، Doctor خطایی صریح گزارش می‌کند؛ آن را دوباره اجرا کنید تا وضعیت پاک را گزارش دهد.

تنزل نسخه‌ها پشتیبانی نمی‌شود

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

رویه کلی به این صورت است:

1. طرح‌واره و مهاجرت‌های انتشار مقصد را بخوانید.
2. در یک تراکنش، همه جدول‌ها، نمایه‌ها، محرک‌ها و ستون‌هایی را که پس از نسخه مقصد افزوده شده‌اند، حذف کنید.
3. مقادیر PRAGMA user_version و schema_meta.schema_version را روی نسخه مقصد تنظیم کنید.
4. پیش از راه‌اندازی Gateway، اعتبارسنجی کامل پایگاه داده انتشار مقصد را اجرا کنید.

مثال: طرح‌واره عامل 11 به 9

طرح‌واره 10 تصویر رونوشت فعال را افزود. طرح‌واره 11 اجاره‌ها، تحویل پایدار، وضعیت نشانی مکالمه و نتایج Heartbeat را افزود. هماهنگی QMD از ردیف‌های state_leases استفاده می‌کند؛ هیچ جدول جداگانه‌ای برای QMD وجود ندارد که لازم باشد حفظ شود.

پس از بررسی طرح‌واره دقیقی که هر پایگاه داده را نوشته است، SQL معادل را روی هر پایگاه داده تحت‌تأثیرِ مختص عامل اجرا کنید:

BEGIN IMMEDIATE; DROP TABLE IF EXISTS heartbeat_outcomes;DROP TABLE IF EXISTS conversation_deliveries;DROP TABLE IF EXISTS state_leases;DROP TABLE IF EXISTS session_transcript_active_events; ALTER TABLE session_transcript_index_state DROP COLUMN active_event_count;ALTER TABLE session_transcript_index_state DROP COLUMN active_message_count;ALTER TABLE conversations DROP COLUMN delivery_target; PRAGMA user_version = 9;UPDATE schema_metaSET schema_version = 9,    updated_at = unixepoch('now') * 1000WHERE meta_key = 'primary'; COMMIT;

این کار وضعیت نسخه‌های 10-11، از جمله عملیات تحویل در حال انجام، اجاره‌ها، نتایج Heartbeat و تصویر مشتق‌شده رونوشت فعال را دور می‌ریزد. اگر تنزل نسخه خراب انجام شود، باید نسخه پشتیبان اعتبارسنجی‌شده را بازیابی کنید.