CLI commands
پشتیبانگیری
openclaw backup
یک بایگانی پشتیبان محلی برای وضعیت، پیکربندی، پروفایلهای احراز هویت، اطلاعات محرمانه کانال/ارائهدهنده، نشستها و در صورت تمایل فضاهای کاری OpenClaw ایجاد کنید.
openclaw backup createopenclaw backup create --output ~/Backupsopenclaw backup create --dry-run --jsonopenclaw backup create --verifyopenclaw backup create --no-include-workspaceopenclaw backup create --only-configopenclaw backup verify ./2026-03-09T08-00-00.000+08-00-openclaw-backup.tar.gzopenclaw backup sqlite create --global --repository ~/Backups/openclaw-sqliteopenclaw backup sqlite create --agent main --repository ~/Backups/openclaw-sqliteopenclaw backup sqlite list --repository ~/Backups/openclaw-sqliteopenclaw backup sqlite verify ~/Backups/openclaw-sqlite/<snapshot-id>openclaw backup sqlite verify ~/Backups/openclaw-sqlite/<snapshot-id> --scratch ~/Private/openclaw-scratchopenclaw backup sqlite restore ~/Backups/openclaw-sqlite/<snapshot-id> --target ./restored/openclaw.sqliteنکات
- بایگانی یک
manifest.jsonرا با مسیرهای مبدأ تفکیکشده و چیدمان بایگانی درون خود جای میدهد. - خروجی پیشفرض یک بایگانی
.tar.gzدارای مُهر زمانی در پوشه کاری فعلی است. نام فایلهای دارای مُهر زمانی از منطقه زمانی محلی دستگاه شما استفاده میکنند و اختلاف با UTC را در بر میگیرند. اگر پوشه کاری فعلی داخل یکی از درختهای مبدأ پشتیبانگیریشده باشد، OpenClaw برای مکان پیشفرض بایگانی از پوشه خانگی شما استفاده میکند. - فایلهای بایگانی موجود هرگز بازنویسی نمیشوند. مسیرهای خروجی داخل درختهای وضعیت/فضای کاری مبدأ برای جلوگیری از گنجاندن خود بایگانی رد میشوند.
openclaw backup verify <archive>بررسی میکند که بایگانی دقیقاً یک مانیفست ریشه داشته باشد، مسیرهای بایگانی با الگوی پیمایش مسیر و فایلهای جانبی SQLite را رد میکند، وجود همه محتوای اعلامشده در مانیفست را تأیید میکند، شکل فایل هر اسنپشات SQLite را اعتبارسنجی میکند و بررسیهای کامل یکپارچگی و نقش را روی پایگاههای داده متعارف OpenClaw اجرا میکند. طرحوارههای اختصاصی Plugin شفافنشده باقی میمانند، زیرا ممکن است به قابلیتهای SQLite تعریفشده توسط مالک نیاز داشته باشند.openclaw backup create --verifyاین اعتبارسنجی را بلافاصله پس از نوشتن بایگانی اجرا میکند.openclaw backup create --only-configفقط از فایل پیکربندی JSON فعال پشتیبان میگیرد.
اسنپشاتهای SQLite
هنگامی که بهجای یک بایگانی گسترده وضعیت، به یک مصنوع قابلانتقال برای یکی از پایگاههای داده SQLite تحت مالکیت OpenClaw نیاز دارید، از openclaw backup sqlite استفاده کنید.
ایجاد اسنپشات دقیقاً یک مبدأ نامگذاریشده را میپذیرد:
| فرمان | پایگاه داده |
|---|---|
openclaw backup sqlite create --global --repository <dir> |
وضعیت مشترک OpenClaw |
openclaw backup sqlite create --agent <id> --repository <dir> |
یک پایگاه داده برای هر عامل |
مخزن برای هر اسنپشات ثبتشده یک پوشه دارد. هر پوشه اسنپشات دقیقاً شامل موارد زیر است:
manifest.jsondatabase.sqlite
ایجاد اسنپشات پیش از خواندن پایگاه داده زنده، آن را تأیید میکند؛ با استفاده از API پشتیبانگیری آنلاین SQLite، وضعیت ثبتشده WAL را بدون باز نگهداشتن یک تراکنش خواندن طولانی ثبت میکند؛ پایگاه داده زنده را میبندد؛ نسخه خصوصی را با VACUUM فشرده میکند؛ پایگاه داده تولیدشده را دوباره تأیید میکند؛ و پوشه تکمیلشده را بدون بازنویسی مسیرهای موجود منتشر میکند. اسنپشاتهای سراسری پیش از Compaction، ردیفهای موقت صف تحویل را حذف میکنند تا محتوای حذفشده صف در صفحههای آزاد باقی نماند.
فایلهای زنده .sqlite، -wal، -shm یا -journal را بهعنوان مصنوع قابلانتقال کپی نکنید. فقط پوشههای اسنپشات تکمیلشده را کپی کنید.
اسنپشاتهای SQLite ممکن است شامل پروفایلهای احراز هویت، وضعیت نشست، وضعیت Plugin و سایر رکوردهای حساس باشند. از مخزنها با همان مجوزها، رمزنگاری، خطمشی نگهداری و محدودیتهای مقصد پوشه وضعیت زنده OpenClaw محافظت کنید.
تأیید و بازیابی
openclaw backup sqlite verify <snapshot-directory>openclaw backup sqlite restore <snapshot-directory> --target <new-database-path>تأیید، شکل سختگیرانه مانیفست، اندازه مصنوع و SHA-256، یکپارچگی SQLite، کلیدهای خارجی، نسخه طرحواره، نقش و مالک پایگاه داده و تعریف نمایههای تحت مالکیت OpenClaw را بررسی میکند.
تأیید، یک نسخه خصوصی با محتوای تثبیتشده را اعتبارسنجی میکند تا رقابتهای نام مسیر نتوانند بایتهایی را که SQLite بررسی میکند جایگزین کنند. بهطور پیشفرض، آن نسخه موقت کنار مخزن اسنپشات ایجاد و پیش از بازگشت فرمان حذف میشود. ریشه مرحلهبندی و زنجیره اجداد آن باید مانع جایگزینی آن توسط کاربران دیگر شوند. ریشههای POSIX باید متعلق به کاربر فعلی باشند و برای گروه/همگان قابلنوشتن نباشند؛ اجداد چسبنده مانند /tmp برای فرزندان متعلق به کاربر پذیرفته میشوند. مجوزهای ACL در macOS که مرحلهبندی را در معرض دسترسی قرار دهند یا قابلجایگزینی کنند، رد میشوند. ریشهها و اجداد در Windows باید متعلق به کاربر فعلی یا یک هویت مورداعتماد سیستمعامل باشند و ACLهایی داشته باشند که دسترسی نامطمئن به مرحلهبندی را منع کنند. برای یک اتصال فقطخواندنی یا اشتراک شبکه، --scratch <existing-private-directory> را روی فضای ذخیرهسازی دارای کنترلهای رمزنگاری و مقصد معادل ارائه کنید.
ایجاد اسنپشات، پیش از مرحلهبندی یا انتشار بایتهای پایگاه داده، همان بررسیهای مالک، ACL، اجداد و هویت مسیر را روی مخزن اعمال میکند.
بازیابی، تأیید را تکرار میکند و فقط در یک مقصد تازه مینویسد. مقصد موجود، فایل جانبی -wal، -shm یا -journal را نمیپذیرد و هرگز پایگاه داده زنده OpenClaw را درجا جایگزین نمیکند. پوشه والد مقصد همان الزامات امنیت مسیر فضای موقت تأیید را دارد. فعالسازی یک پایگاه داده بازیابیشده همچنان یک مرحله آفلاین و صریح اپراتور است.
مخزنهای اسنپشات پوشههای محلی هستند. زمانبندی، بارگذاری، نگهداری، بستههای افزایشی WAL، جایگزینی هنگام خرابی و رفتار بازیابی هنگام راهاندازی عمداً خارج از محدوده این فرمان هستند.
از چه چیزهایی پشتیبان گرفته میشود
openclaw backup create مبدأها را از نصب محلی OpenClaw شما برنامهریزی میکند:
- پوشه وضعیت (معمولاً
~/.openclaw) - مسیر فایل پیکربندی فعال
- پوشه تفکیکشده
credentials/، هنگامی که خارج از پوشه وضعیت وجود داشته باشد - پوشههای فضای کاری کشفشده از پیکربندی فعلی، مگر اینکه
--no-include-workspaceرا ارائه کنید
پروفایلهای احراز هویت و سایر وضعیتهای زمان اجرای هر عامل در SQLite زیر پوشه وضعیت (agents/<agentId>/agent/openclaw-agent.sqlite) قرار دارند؛ بنابراین ورودی پشتیبان وضعیت بهطور خودکار آنها را پوشش میدهد.
--only-config از کشف وضعیت، پوشه اطلاعات محرمانه و فضای کاری صرفنظر میکند و فقط مسیر فایل پیکربندی فعال را بایگانی میکند.
OpenClaw پیش از ساخت بایگانی مسیرها را متعارف میکند: اگر پیکربندی، پوشه اطلاعات محرمانه یا یک فضای کاری از قبل داخل پوشه وضعیت باشند، بهعنوان مبدأهای جداگانه سطح بالای پشتیبان تکرار نمیشوند. مسیرهای ناموجود نادیده گرفته میشوند.
هنگام ایجاد بایگانی، OpenClaw پیش از آنکه tar مسیرها را بخواند، مسیرهای شناختهشده دارای تغییرات زنده را حذف میکند. این کار از رقابت میان اندازه ثبتشده فایل و نوشتنهای همزمان جلوگیری میکند. این فیلتر قواعد نسبی زیر را زیر هر پوشه وضعیت پشتیبانگیریشده اعمال میکند:
| محدوده نسبی به وضعیت | پسوندهای فایل نادیدهگرفتهشده |
|---|---|
sessions/** |
.jsonl، .log |
agents/<agentId>/sessions/** |
.jsonl، .log |
cron/runs/** |
.jsonl، .log |
logs/** |
.jsonl، .log |
delivery-queue/** |
.json، .delivered، .tmp |
session-delivery-queue/** |
.json، .delivered، .tmp |
| هر مسیر زیر پوشه وضعیت پشتیبانگیریشده | .sock، .pid، .tmp |
این قواعد فایلهای فضای کاری خارج از پوشه وضعیت را فیلتر نمیکنند. همچنین فایلهای کاملشده رونوشت و گزارش منطبق با جدول را حذف میکنند؛ بنابراین در صورت نیاز، آن رکوردها را جداگانه نگه دارید. مقدار skippedVolatileCount در نتیجه JSON تعداد فایلهایی را گزارش میکند که عمداً حذف شدهاند.
پایگاههای داده SQLite زیر پوشه وضعیت با API پشتیبانگیری آنلاین SQLite ثبت و بهصورت آفلاین با VACUUM فشرده میشوند تا بقایای صفحههای حذفشده وارد بایگانی نشوند و فایلهای زنده WAL/SHM کپی نشوند. پایگاه داده تحت مالکیت Plugin که به قابلیتهای SQLite تعریفشده توسط مالک و در دسترسنبوده نیاز دارد، بهصورت بسته خطا میدهد و به کپی مستقیم فایل بازنمیگردد. فایلهای SQLite که از طریق پشتیبانهای فضای کاری گنجانده میشوند، مانند فایلهای فضای کاری کپی میشوند و تضمین Compaction آنها را پوشش نمیدهد.
فایلهای مبدأ و مانیفست Pluginهای نصبشده زیر درخت extensions/ پوشه وضعیت گنجانده میشوند، اما درختهای وابستگی تودرتوی node_modules/ آنها بهعنوان مصنوعات نصب قابلبازسازی نادیده گرفته میشوند. پس از بازیابی یک بایگانی، اگر Plugin بازیابیشده وابستگیهای مفقود را گزارش کرد، از openclaw plugins update <id> استفاده کنید یا با openclaw plugins install <spec> --force دوباره نصب کنید.
ریشههای زمان اجرای مدیریتشده توسط نصبکننده و قابلبازسازی زیر پوشه وضعیت نیز نادیده گرفته میشوند: dev/، git/، npm/، npm-runtime/ قدیمی و tools/. اینها بهجای وضعیت معتبر کاربر، شامل تسویهحسابهای مدیریتشده، درختهای بسته و زمانهای اجرای بارگیریشده هستند؛ پس از بازیابی، زمان اجرا یا Plugin مربوطه را دوباره نصب یا بهروزرسانی کنید. فایل پیکربندی، پوشه اطلاعات محرمانه یا فضای کاری که صریحاً داخل یکی از این ریشهها پیکربندی شده باشد، همچنان گنجانده میشود.
رفتار پیکربندی نامعتبر
openclaw backup پیشبررسی معمول پیکربندی را دور میزند تا همچنان بتواند هنگام بازیابی کمک کند. کشف فضای کاری به پیکربندی معتبر وابسته است؛ بنابراین وقتی فایل پیکربندی وجود دارد اما نامعتبر است و پشتیبانگیری از فضای کاری همچنان فعال است، openclaw backup create بیدرنگ با خطا متوقف میشود.
برای پشتیبانگیری جزئی در چنین وضعیتی، دوباره با --no-include-workspace اجرا کنید: وضعیت، پیکربندی و پوشه خارجی اطلاعات محرمانه را در محدوده نگه میدارد و در عین حال از کشف فضای کاری کاملاً صرفنظر میکند.
--only-config نیز هنگامی که پیکربندی بدشکل است کار میکند، زیرا برای کشف فضای کاری پیکربندی را تجزیه نمیکند.
اندازه و کارایی
OpenClaw حداکثر اندازه داخلی برای پشتیبان یا محدودیت اندازه هر فایل اعمال نمیکند. اگر نوشتن بایگانی بهمدت پنج دقیقه هیچ دادهای تولید نکند، عملیات با خطا متوقف میشود و بهجای آویزانماندن نامحدود، فایل موقت ناقص خود را حذف میکند. در غیر این صورت، محدودیتهای عملی از موارد زیر ناشی میشوند:
- فضای موجود برای نوشتن بایگانی موقت بهعلاوه بایگانی نهایی
- زمان لازم برای پیمایش درختهای بزرگ فضای کاری و فشردهسازی آنها در یک
.tar.gz - زمان لازم برای اسکن مجدد بایگانی با
--verifyیاopenclaw backup verify - رفتار سیستم فایل مقصد: OpenClaw به انتشار با پیوند سختِ بدون بازنویسی نیاز دارد تا مسیر بایگانی نهایی هرگز نسخه در حال تکمیل را نمایش ندهد؛ سیستمهای فایل پشتیبانینشده با خطایی قابلاقدام متوقف میشوند
اگر تأیید دوام پوشه نهایی پس از انتشار ناموفق باشد، فرمان شکست را گزارش میکند، اما بهجای خطر حذف یک جایگزین همزمان، ورودی نهایی کامل را حفظ میکند.
فضاهای کاری بزرگ معمولاً عامل اصلی اندازه بایگانی هستند. برای پشتیبان کوچکتر/سریعتر از --no-include-workspace یا برای کوچکترین بایگانی از --only-config استفاده کنید.