---
read_when:
    - عیب‌یابی خطای طرح‌واره جدیدتر پایگاه داده
    - بررسی سازگاری پایگاه داده پیش از به‌روزرسانی یا بازگشت به نسخه قبلی
    - بازیابی پایگاه داده برای نسخه‌ای قدیمی‌تر از OpenClaw
summary: محل پایگاه‌های داده SQLite در OpenClaw، نسخه‌های شِما، بررسی‌های یکپارچگی و بازیابی پس از تنزل نسخه
title: طرح‌واره‌های پایگاه داده
x-i18n:
    generated_at: "2026-07-27T14:35:16Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 73993e2c593ba460784108aedef70bbfb499e525c709d6d6bdd956ccf93e0ddc
    source_path: reference/database-schemas.md
    workflow: 16
---

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

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

| دامنه                | مسیر پیش‌فرض                                               | محتویات                                                                                              |
| -------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| صفحه کنترل سراسری | `~/.openclaw/state/openclaw.sqlite`                        | وضعیت پیکربندی مشترک، رجیستری‌ها، تأییدها، وضعیت Plugin و وضعیت زمان اجرای مشترک             |
| صفحه داده هر عامل | `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite` | نشست‌ها، رونوشت‌ها، نمایه‌های حافظه، وضعیت احراز هویت، وضعیت مکالمه و وضعیت زمان اجرای مختص عامل |

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

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

| نسخه | تغییر                                                                                                                                                                                                                                                         | نخستین انتشار                                   |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| 1       | ذخیره‌گاه اولیه هر عامل ([#88349](https://github.com/openclaw/openclaw/pull/88349))                                                                                                                                                                            | `v2026.5.30-beta.1`، پایدار تا `v2026.7.1` |
| 2       | هویت نمایه حافظه ([#104449](https://github.com/openclaw/openclaw/pull/104449))                                                                                                                                                                            | `v2026.7.2-beta.1`                              |
| 4       | انتقال نشست‌ها و رونوشت‌ها به SQLite ([#98236](https://github.com/openclaw/openclaw/pull/98236))                                                                                                                                                         | `v2026.7.2-beta.1`                              |
| 5-6     | تازگی ترمینال و چرخه عمر وضعیت ([#104859](https://github.com/openclaw/openclaw/pull/104859))                                                                                                                                                           | `v2026.7.2-beta.1`                              |
| 7       | تصویر وضعیت چرخه عمر هر ورودی ([#106151](https://github.com/openclaw/openclaw/pull/106151))                                                                                                                                                            | `v2026.7.2-beta.1`                              |
| 8       | منشأ نشست برای هر رونوشت ([#106766](https://github.com/openclaw/openclaw/pull/106766))                                                                                                                                                                | `v2026.7.2-beta.2`                              |
| 9       | جدول‌های `STRICT` ([#108663](https://github.com/openclaw/openclaw/pull/108663))                                                                                                                                                                                  | `v2026.7.2-beta.2`                              |
| 10      | مسیرهای مادی‌سازی‌شده رونوشت فعال ([#108851](https://github.com/openclaw/openclaw/pull/108851))                                                                                                                                                             | منتشرنشده                                      |
| 11      | اجاره‌ها، تحویل پایدار، نشانی‌های مکالمه و نتایج Heartbeat ([#109636](https://github.com/openclaw/openclaw/pull/109636)، [#95838](https://github.com/openclaw/openclaw/pull/95838)، [#109999](https://github.com/openclaw/openclaw/pull/109999)) | منتشرنشده                                      |

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

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

| نسخه | تغییر                                                                                                   | نخستین انتشار       |
| ------- | -------------------------------------------------------------------------------------------------------- | ------------------- |
| 1       | پایگاه داده اولیه وضعیت مشترک                                                                            | `v2026.5.30-beta.1` |
| 2       | رویدادهای ممیزی پیامِ صرفاً شامل فراداده ([#103903](https://github.com/openclaw/openclaw/pull/103903))         | `v2026.7.2-beta.1`  |
| 3       | جدول‌های `STRICT` و مقاوم‌سازی در برابر انحراف طرح‌واره ([#108663](https://github.com/openclaw/openclaw/pull/108663)) | `v2026.7.2-beta.2`  |
| 4       | منشأ پایش نشست جایگزین ردیف‌های نگهبان کدگذاری‌شده می‌شود                                                  | منتشرنشده          |

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

| زمان                                        | بررسی                                                           |
| ------------------------------------------- | --------------------------------------------------------------- |
| هر بار باز شدن                                  | اعتبارسنجی جدول `schema_meta` و ردیف فراداده اصلی       |
| پیش از یک مهاجرت در انتظار                  | اجرای اسکن کامل یکپارچگی، کلید خارجی، نقش، طرح‌واره و نمایه |
| اعتبارسنج پس‌زمینه Gateway                 | اجرای اسکن کامل تقریباً روزی یک بار و ثبت نتایج              |
| Doctor، اعتبارسنجی پشتیبان و Compaction | اجرای اسکن کامل پیش از پذیرش یا بازنویسی پایگاه داده    |

پیش‌بررسی 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. یک نسخه پشتیبان تهیه‌شده پیش از به‌روزرسانی را بازیابی کنید. پیش از به‌روزرسانی‌های عمده، [نسخه‌های پشتیبان را ایجاد و اعتبارسنجی کنید](/fa/cli/backup).
2. نسخه قدیمی‌تر را با یک پوشه وضعیت جداگانه (`OPENCLAW_STATE_DIR`) اجرا کنید. این نسخه از ابتدا شروع می‌کند؛ داده‌های مهاجرت‌یافته برای زمانی که به نسخه جدیدتر بازگردید، دست‌نخورده باقی می‌مانند.
3. رویه تنزل نسخه دستی زیر را دنبال کنید. این روش پشتیبانی نمی‌شود و بدون یک نسخه پشتیبان اعتبارسنجی‌شده، خطر از دست رفتن داده‌ها را دارد.

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

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

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

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

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

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

تنزل دستی طرح‌واره برای عامل‌ها و اپراتورهایی است که این خطر را می‌پذیرند. پیش از ویرایش هر پایگاه داده، [یک نسخه پشتیبان ایجاد و اعتبارسنجی کنید](/fa/cli/backup). Gateway و همه فرایندهایی را که می‌توانند پایگاه داده را باز کنند، متوقف کنید.

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

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

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

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

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

```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_meta
SET schema_version = 9,
    updated_at = unixepoch('now') * 1000
WHERE meta_key = 'primary';

COMMIT;
```

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