مهاجرت Matrix

از Plugin عمومی قبلی matrix به پیاده‌سازی فعلی ارتقا دهید.

برای بیشتر کاربران، ارتقا درجا انجام می‌شود:

• Plugin همان @OmeniaClaw/matrix می‌ماند
• کانال همان matrix می‌ماند
• پیکربندی شما زیر channels.matrix می‌ماند
• اعتبارنامه‌های کش‌شده زیر ~/.OmeniaClaw/credentials/matrix/ می‌مانند
• وضعیت زمان اجرا زیر ~/.OmeniaClaw/matrix/ می‌ماند

نیازی نیست کلیدهای پیکربندی را تغییر نام دهید یا Plugin را با نام جدیدی دوباره نصب کنید.

مهاجرت به‌صورت خودکار چه کارهایی انجام می‌دهد

وقتی Gateway شروع به کار می‌کند، و وقتی OmeniaClaw doctor --fix را اجرا می‌کنید، OmeniaClaw تلاش می‌کند وضعیت قدیمی Matrix را به‌صورت خودکار ترمیم کند. پیش از آنکه هر گام قابل‌اقدام مهاجرت Matrix وضعیت روی دیسک را تغییر دهد، OmeniaClaw یک اسنپ‌شات بازیابی متمرکز ایجاد می‌کند یا از آن دوباره استفاده می‌کند.

وقتی از OmeniaClaw update استفاده می‌کنید، محرک دقیق به نحوه نصب OmeniaClaw بستگی دارد:

• نصب‌های از منبع، در جریان به‌روزرسانی OmeniaClaw doctor --fix را اجرا می‌کنند، سپس به‌طور پیش‌فرض Gateway را دوباره راه‌اندازی می‌کنند
• نصب‌های مدیر بسته، بسته را به‌روزرسانی می‌کنند، یک گذر doctor غیرتعاملی اجرا می‌کنند، سپس به راه‌اندازی دوباره پیش‌فرض Gateway تکیه می‌کنند تا شروع به کار بتواند مهاجرت Matrix را کامل کند
• اگر از OmeniaClaw update --no-restart استفاده کنید، مهاجرت Matrix مبتنی بر شروع به کار تا زمانی که بعدا OmeniaClaw doctor --fix را اجرا کنید و Gateway را دوباره راه‌اندازی کنید به تعویق می‌افتد

مهاجرت خودکار شامل این موارد است:

• ایجاد یا استفاده دوباره از اسنپ‌شات پیش از مهاجرت زیر ~/Backups/OmeniaClaw-migrations/
• استفاده دوباره از اعتبارنامه‌های Matrix کش‌شده شما
• حفظ همان انتخاب حساب و پیکربندی channels.matrix
• انتقال قدیمی‌ترین ذخیره‌گاه همگام‌سازی تخت Matrix به مکان فعلی با دامنه حساب
• انتقال قدیمی‌ترین ذخیره‌گاه کریپتوی تخت Matrix به مکان فعلی با دامنه حساب، وقتی حساب مقصد را بتوان با اطمینان تعیین کرد
• استخراج کلید رمزگشایی پشتیبان کلید اتاق Matrix که قبلا ذخیره شده است، از ذخیره‌گاه کریپتوی rust قدیمی، وقتی آن کلید به‌صورت محلی وجود داشته باشد
• استفاده دوباره از کامل‌ترین ریشه ذخیره‌سازی هش توکن موجود برای همان حساب Matrix، homeserver و کاربر، وقتی توکن دسترسی بعدا تغییر کند
• اسکن ریشه‌های ذخیره‌سازی هش توکن هم‌سطح برای فراداده بازیابی وضعیت رمزگذاری‌شده در انتظار، وقتی توکن دسترسی Matrix تغییر کرده اما هویت حساب/دستگاه همان مانده است
• بازیابی کلیدهای اتاق پشتیبان‌گیری‌شده در ذخیره‌گاه کریپتوی جدید در شروع بعدی Matrix

جزئیات اسنپ‌شات:

• OmeniaClaw پس از اسنپ‌شات موفق، یک فایل نشانگر در ~/.OmeniaClaw/matrix/migration-snapshot.json می‌نویسد تا گذرهای بعدی شروع به کار و ترمیم بتوانند از همان آرشیو دوباره استفاده کنند.
• این اسنپ‌شات‌های خودکار مهاجرت Matrix فقط از پیکربندی + وضعیت پشتیبان می‌گیرند (includeWorkspace: false).
• اگر Matrix فقط وضعیت مهاجرت هشدارگونه داشته باشد، برای مثال چون userId یا accessToken هنوز وجود ندارد، OmeniaClaw هنوز اسنپ‌شات را ایجاد نمی‌کند، چون هیچ تغییر Matrix قابل‌اقدامی وجود ندارد.
• اگر گام اسنپ‌شات شکست بخورد، OmeniaClaw به‌جای تغییر وضعیت بدون نقطه بازیابی، مهاجرت Matrix را برای آن اجرا نادیده می‌گیرد.

درباره ارتقاهای چندحسابی:

• قدیمی‌ترین ذخیره‌گاه تخت Matrix (~/.OmeniaClaw/matrix/bot-storage.json و ~/.OmeniaClaw/matrix/crypto/) از یک چیدمان تک‌ذخیره‌گاهی آمده است، بنابراین OmeniaClaw فقط می‌تواند آن را به یک مقصد حساب Matrix تعیین‌شده مهاجرت دهد
• ذخیره‌گاه‌های قدیمی Matrix که از قبل دامنه حساب دارند، برای هر حساب Matrix پیکربندی‌شده شناسایی و آماده می‌شوند

مهاجرت چه کارهایی را نمی‌تواند خودکار انجام دهد

Plugin عمومی قبلی Matrix به‌صورت خودکار پشتیبان کلید اتاق Matrix ایجاد نمی‌کرد. وضعیت کریپتوی محلی را پایدار می‌کرد و درخواست راستی‌آزمایی دستگاه می‌داد، اما تضمین نمی‌کرد که کلیدهای اتاق شما در homeserver پشتیبان‌گیری شده باشند.

این یعنی برخی نصب‌های رمزگذاری‌شده فقط می‌توانند به‌صورت جزئی مهاجرت شوند.

OmeniaClaw نمی‌تواند به‌صورت خودکار این موارد را بازیابی کند:

• کلیدهای اتاق فقط‌محلی که هرگز پشتیبان‌گیری نشده‌اند
• وضعیت رمزگذاری‌شده وقتی حساب Matrix مقصد هنوز قابل تعیین نیست، چون homeserver، userId یا accessToken هنوز در دسترس نیستند
• مهاجرت خودکار یک ذخیره‌گاه تخت Matrix مشترک وقتی چند حساب Matrix پیکربندی شده‌اند اما channels.matrix.defaultAccount تنظیم نشده است
• نصب‌های مسیر سفارشی Plugin که به‌جای بسته استاندارد Matrix به مسیر یک مخزن پین شده‌اند
• کلید بازیابی گم‌شده وقتی ذخیره‌گاه قدیمی کلیدهای پشتیبان‌گیری‌شده داشت اما کلید رمزگشایی را به‌صورت محلی نگه نداشته بود

دامنه هشدار فعلی:

• نصب‌های مسیر سفارشی Plugin مربوط به Matrix هم توسط شروع به کار Gateway و هم توسط OmeniaClaw doctor نمایش داده می‌شوند

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

جریان ارتقای پیشنهادی

1. OmeniaClaw و Plugin مربوط به Matrix را به‌طور معمول به‌روزرسانی کنید. OmeniaClaw update ساده را بدون --no-restart ترجیح دهید تا شروع به کار بتواند مهاجرت Matrix را بلافاصله کامل کند.

2. اجرا کنید:

   OmeniaClaw doctor --fix

   اگر Matrix کار مهاجرت قابل‌اقدام داشته باشد، doctor ابتدا اسنپ‌شات پیش از مهاجرت را ایجاد می‌کند یا از آن دوباره استفاده می‌کند و مسیر آرشیو را چاپ می‌کند.

3. Gateway را شروع یا دوباره راه‌اندازی کنید.

4. وضعیت فعلی راستی‌آزمایی و پشتیبان را بررسی کنید:

   OmeniaClaw matrix verify statusOmeniaClaw matrix verify backup status

5. کلید بازیابی حساب Matrix را که در حال ترمیم آن هستید در یک متغیر محیطی مخصوص حساب قرار دهید. برای یک حساب پیش‌فرض واحد، MATRIX_RECOVERY_KEY کافی است. برای چند حساب، برای هر حساب یک متغیر استفاده کنید، برای مثال MATRIX_RECOVERY_KEY_ASSISTANT، و --account assistant را به فرمان اضافه کنید.

6. اگر OmeniaClaw به شما گفت که کلید بازیابی لازم است، فرمان را برای حساب متناظر اجرا کنید:

   printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify backup restore --recovery-key-stdinprintf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | OmeniaClaw matrix verify backup restore --recovery-key-stdin --account assistant

7. اگر این دستگاه هنوز راستی‌آزمایی نشده است، فرمان را برای حساب متناظر اجرا کنید:

   printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify device --recovery-key-stdinprintf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | OmeniaClaw matrix verify device --recovery-key-stdin --account assistant

   اگر کلید بازیابی پذیرفته شد و پشتیبان قابل استفاده بود، اما Cross-signing verified هنوز no است، خودراستی‌آزمایی را از یک کلاینت Matrix دیگر کامل کنید:

   OmeniaClaw matrix verify self

   درخواست را در یک کلاینت Matrix دیگر بپذیرید، ایموجی یا اعداد اعشاری را مقایسه کنید، و فقط وقتی مطابقت دارند yes را تایپ کنید. فرمان فقط پس از آنکه Cross-signing verified به yes تبدیل شود با موفقیت خارج می‌شود.

8. اگر عمدا تاریخچه قدیمی غیرقابل‌بازیابی را کنار می‌گذارید و برای پیام‌های آینده یک خط پایه پشتیبان تازه می‌خواهید، اجرا کنید:

   OmeniaClaw matrix verify backup reset --yes

9. اگر هنوز هیچ پشتیبان کلید سمت سرور وجود ندارد، برای بازیابی‌های آینده یکی بسازید:

   OmeniaClaw matrix verify bootstrap

مهاجرت رمزگذاری‌شده چگونه کار می‌کند

مهاجرت رمزگذاری‌شده یک فرایند دو مرحله‌ای است:

1. شروع به کار یا OmeniaClaw doctor --fix، اگر مهاجرت رمزگذاری‌شده قابل‌اقدام باشد، اسنپ‌شات پیش از مهاجرت را ایجاد می‌کند یا از آن دوباره استفاده می‌کند.
2. شروع به کار یا OmeniaClaw doctor --fix، ذخیره‌گاه کریپتوی قدیمی Matrix را از طریق نصب فعال Plugin مربوط به Matrix بررسی می‌کند.
3. اگر کلید رمزگشایی پشتیبان پیدا شود، OmeniaClaw آن را در جریان جدید کلید بازیابی می‌نویسد و بازیابی کلید اتاق را به‌عنوان در انتظار علامت‌گذاری می‌کند.
4. در شروع بعدی Matrix، OmeniaClaw به‌صورت خودکار کلیدهای اتاق پشتیبان‌گیری‌شده را در ذخیره‌گاه کریپتوی جدید بازیابی می‌کند.

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

پیام‌های رایج و معنای آن‌ها

پیام‌های ارتقا و تشخیص

Matrix plugin upgraded in place.

• معنی: وضعیت قدیمی Matrix روی دیسک شناسایی شد و به چیدمان فعلی مهاجرت داده شد.
• چه باید کرد: هیچ کاری، مگر اینکه همان خروجی شامل هشدارها نیز باشد.

Matrix migration snapshot created before applying Matrix upgrades.

• معنی: OmeniaClaw پیش از تغییر وضعیت Matrix یک آرشیو بازیابی ایجاد کرد.
• چه باید کرد: مسیر آرشیو چاپ‌شده را تا زمانی که تأیید کنید مهاجرت موفق بوده نگه دارید.

Matrix migration snapshot reused before applying Matrix upgrades.

• معنی: OmeniaClaw یک نشانگر اسنپ‌شات مهاجرت Matrix موجود پیدا کرد و به‌جای ایجاد پشتیبان تکراری، از همان آرشیو دوباره استفاده کرد.
• چه باید کرد: مسیر آرشیو چاپ‌شده را تا زمانی که تأیید کنید مهاجرت موفق بوده نگه دارید.

Legacy Matrix state detected at ... but channels.matrix is not configured yet.

• معنی: وضعیت قدیمی Matrix وجود دارد، اما OmeniaClaw نمی‌تواند آن را به یک حساب Matrix فعلی نگاشت کند، چون Matrix پیکربندی نشده است.
• چه باید کرد: channels.matrix را پیکربندی کنید، سپس OmeniaClaw doctor --fix را دوباره اجرا کنید یا Gateway را دوباره راه‌اندازی کنید.

Legacy Matrix state detected at ... but the new account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).

• معنی: OmeniaClaw وضعیت قدیمی را پیدا کرد، اما هنوز نمی‌تواند ریشه دقیق حساب/دستگاه فعلی را تعیین کند.
• چه باید کرد: Gateway را یک بار با ورود Matrix سالم شروع کنید، یا پس از وجود اعتبارنامه‌های کش‌شده OmeniaClaw doctor --fix را دوباره اجرا کنید.

Legacy Matrix state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.

• معنی: OmeniaClaw یک ذخیره‌گاه تخت Matrix مشترک پیدا کرد، اما حدس نمی‌زند کدام حساب نام‌دار Matrix باید آن را دریافت کند.
• چه باید کرد: channels.matrix.defaultAccount را روی حساب موردنظر تنظیم کنید، سپس OmeniaClaw doctor --fix را دوباره اجرا کنید یا Gateway را دوباره راه‌اندازی کنید.

Matrix legacy sync store not migrated because the target already exists (...)

• معنی: مکان جدید با دامنه حساب از قبل یک ذخیره‌گاه همگام‌سازی یا کریپتو دارد، بنابراین OmeniaClaw آن را به‌صورت خودکار بازنویسی نکرد.
• چه باید کرد: پیش از حذف یا انتقال دستی مقصد متعارض، بررسی کنید که حساب فعلی همان حساب درست است.

Failed migrating Matrix legacy sync store (...) یا Failed migrating Matrix legacy crypto store (...)

• معنی: OmeniaClaw تلاش کرد وضعیت قدیمی Matrix را منتقل کند اما عملیات فایل‌سیستم شکست خورد.
• چه باید کرد: مجوزهای فایل‌سیستم و وضعیت دیسک را بررسی کنید، سپس OmeniaClaw doctor --fix را دوباره اجرا کنید.

Legacy Matrix encrypted state detected at ... but channels.matrix is not configured yet.

• معنی: OmeniaClaw یک ذخیره‌گاه رمزگذاری‌شده قدیمی Matrix پیدا کرد، اما هیچ پیکربندی فعلی Matrix برای اتصال آن وجود ندارد.
• چه باید کرد: channels.matrix را پیکربندی کنید، سپس OmeniaClaw doctor --fix را دوباره اجرا کنید یا Gateway را دوباره راه‌اندازی کنید.

Legacy Matrix encrypted state detected at ... but the account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).

• معنی: ذخیره‌گاه رمزگذاری‌شده وجود دارد، اما OmeniaClaw نمی‌تواند با اطمینان تصمیم بگیرد متعلق به کدام حساب/دستگاه فعلی است.
• چه باید کرد: Gateway را یک بار با ورود Matrix سالم شروع کنید، یا پس از در دسترس بودن اعتبارنامه‌های کش‌شده OmeniaClaw doctor --fix را دوباره اجرا کنید.

Legacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.

• معنی: OmeniaClaw یک ذخیره‌گاه کریپتوی قدیمی تخت مشترک پیدا کرد، اما حدس نمی‌زند کدام حساب نام‌دار Matrix باید آن را دریافت کند.
• چه باید کرد: channels.matrix.defaultAccount را روی حساب موردنظر تنظیم کنید، سپس OmeniaClaw doctor --fix را دوباره اجرا کنید یا Gateway را دوباره راه‌اندازی کنید.

Matrix migration warnings are present, but no on-disk Matrix mutation is actionable yet. No pre-migration snapshot was needed.

• معنی: OmeniaClaw وضعیت قدیمی Matrix را تشخیص داد، اما مهاجرت هنوز به‌دلیل نبود داده هویت یا اعتبارنامه مسدود است.
• چه باید کرد: ورود Matrix یا تنظیم پیکربندی را کامل کنید، سپس OmeniaClaw doctor --fix را دوباره اجرا کنید یا Gateway را دوباره راه‌اندازی کنید.

Legacy Matrix encrypted state was detected, but the Matrix plugin helper is unavailable. Install or repair @OmeniaClaw/matrix so OmeniaClaw can inspect the old rust crypto store before upgrading.

• معنی: OmeniaClaw وضعیت رمزگذاری‌شده قدیمی Matrix را پیدا کرد، اما نتوانست نقطه ورود کمکی را از Plugin مربوط به Matrix که معمولا آن ذخیره‌گاه را بررسی می‌کند بارگذاری کند.
• چه باید کرد: Plugin مربوط به Matrix را دوباره نصب یا ترمیم کنید (OmeniaClaw plugins install @OmeniaClaw/matrix، یا برای checkout یک مخزن، OmeniaClaw plugins install ./path/to/local/matrix-plugin)، سپس OmeniaClaw doctor --fix را دوباره اجرا کنید یا Gateway را دوباره راه‌اندازی کنید.

Matrix plugin helper path is unsafe: ... Reinstall @OmeniaClaw/matrix and try again.

• معنی: OmeniaClaw مسیر فایل کمکی‌ای را پیدا کرد که از ریشه Plugin خارج می‌شود یا بررسی‌های مرز Plugin را رد نمی‌کند، بنابراین از import کردن آن خودداری کرد.
• کار لازم: Plugin مربوط به Matrix را از یک مسیر قابل اعتماد دوباره نصب کنید، سپس OmeniaClaw doctor --fix را دوباره اجرا کنید یا Gateway را restart کنید.

- Failed creating a Matrix migration snapshot before repair: ...

- Skipping Matrix migration changes for now. Resolve the snapshot failure, then rerun "OmeniaClaw doctor --fix".

• معنی: OmeniaClaw از تغییر دادن وضعیت Matrix خودداری کرد، چون نتوانست ابتدا snapshot بازیابی را ایجاد کند.
• کار لازم: خطای backup را برطرف کنید، سپس OmeniaClaw doctor --fix را دوباره اجرا کنید یا Gateway را restart کنید.

Failed migrating legacy Matrix client storage: ...

• معنی: fallback سمت کلاینت Matrix، storage تخت قدیمی را پیدا کرد، اما جابه‌جایی شکست خورد. OmeniaClaw اکنون به‌جای اینکه بی‌سروصدا با یک store تازه شروع شود، آن fallback را متوقف می‌کند.
• کار لازم: مجوزهای filesystem یا تداخل‌ها را بررسی کنید، وضعیت قدیمی را دست‌نخورده نگه دارید، و پس از رفع خطا دوباره تلاش کنید.

Matrix is installed from a custom path: ...

• معنی: Matrix به یک نصب مبتنی بر مسیر pin شده است، بنابراین به‌روزرسانی‌های mainline به‌طور خودکار آن را با package استاندارد Matrix در repo جایگزین نمی‌کنند.
• کار لازم: وقتی می‌خواهید به Plugin پیش‌فرض Matrix برگردید، با OmeniaClaw plugins install @OmeniaClaw/matrix دوباره نصب کنید.

پیام‌های بازیابی وضعیت رمزگذاری‌شده

matrix: restored X/Y room key(s) from legacy encrypted-state backup

• معنی: کلیدهای room پشتیبان‌گیری‌شده با موفقیت در crypto store جدید بازیابی شدند.
• کار لازم: معمولاً هیچ کاری لازم نیست.

matrix: N legacy local-only room key(s) were never backed up and could not be restored automatically

• معنی: برخی کلیدهای room قدیمی فقط در store محلی قدیمی وجود داشتند و هرگز در backup مربوط به Matrix upload نشده بودند.
• کار لازم: انتظار داشته باشید بخشی از history رمزگذاری‌شده قدیمی همچنان در دسترس نباشد، مگر اینکه بتوانید آن کلیدها را به‌صورت دستی از یک کلاینت verified دیگر بازیابی کنید.

Legacy Matrix encrypted state for account "..." has backed-up room keys, but no local backup decryption key was found. Ask the operator to run "OmeniaClaw matrix verify backup restore --recovery-key-stdin" after upgrade if they have the recovery key.

• معنی: backup وجود دارد، اما OmeniaClaw نتوانست recovery key را به‌طور خودکار بازیابی کند.
• کار لازم: printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify backup restore --recovery-key-stdin را اجرا کنید.

Failed inspecting legacy Matrix encrypted state for account "..." (...): ...

• معنی: OmeniaClaw store رمزگذاری‌شده قدیمی را پیدا کرد، اما نتوانست آن را به اندازه کافی امن بررسی کند تا بازیابی را آماده کند.
• کار لازم: OmeniaClaw doctor --fix را دوباره اجرا کنید. اگر تکرار شد، دایرکتوری وضعیت قدیمی را دست‌نخورده نگه دارید و با استفاده از یک کلاینت Matrix verified دیگر به‌همراه printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify backup restore --recovery-key-stdin بازیابی کنید.

Legacy Matrix backup key was found for account "...", but .../recovery-key.json already contains a different recovery key. Leaving the existing file unchanged.

• معنی: OmeniaClaw یک تداخل backup key تشخیص داد و از بازنویسی خودکار فایل recovery-key فعلی خودداری کرد.
• کار لازم: پیش از اجرای دوباره هر دستور restore، بررسی کنید کدام recovery key درست است.

Legacy Matrix encrypted state for account "..." cannot be fully converted automatically because the old rust crypto store does not expose all local room keys for export.

• معنی: این محدودیت قطعی format قدیمی storage است.
• کار لازم: کلیدهای پشتیبان‌گیری‌شده همچنان قابل بازیابی هستند، اما history رمزگذاری‌شده local-only ممکن است در دسترس نماند.

matrix: failed restoring room keys from legacy encrypted-state backup: ...

• معنی: Plugin جدید تلاش کرد restore انجام دهد، اما Matrix خطا برگرداند.
• کار لازم: OmeniaClaw matrix verify backup status را اجرا کنید، سپس در صورت نیاز با printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify backup restore --recovery-key-stdin دوباره تلاش کنید.

پیام‌های بازیابی دستی

Backup key is not loaded on this device. Run 'OmeniaClaw matrix verify backup restore' to load it and restore old room keys.

• معنی: OmeniaClaw می‌داند که باید backup key داشته باشید، اما این کلید روی این دستگاه active نیست.
• کار لازم: OmeniaClaw matrix verify backup restore را اجرا کنید، یا در صورت نیاز MATRIX_RECOVERY_KEY را set کنید و printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify backup restore --recovery-key-stdin را اجرا کنید.

Store a recovery key with 'OmeniaClaw matrix verify device --recovery-key-stdin', then run 'OmeniaClaw matrix verify backup restore'.

• معنی: این دستگاه در حال حاضر recovery key را stored ندارد.
• کار لازم: MATRIX_RECOVERY_KEY را set کنید، printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify device --recovery-key-stdin را اجرا کنید، سپس backup را restore کنید.

Backup key mismatch on this device. Re-run 'OmeniaClaw matrix verify device --recovery-key-stdin' with the matching recovery key.

• معنی: کلید stored با backup فعال Matrix مطابقت ندارد.
• کار لازم: MATRIX_RECOVERY_KEY را روی کلید درست set کنید و printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify device --recovery-key-stdin را اجرا کنید.

اگر از دست دادن history رمزگذاری‌شده قدیمیِ غیرقابل بازیابی را می‌پذیرید، می‌توانید در عوض baseline فعلی backup را با OmeniaClaw matrix verify backup reset --yes reset کنید. وقتی secret مربوط به backup stored خراب باشد، این reset ممکن است secret storage را هم دوباره ایجاد کند تا backup key جدید پس از restart درست load شود.

Backup trust chain is not verified on this device. Re-run 'OmeniaClaw matrix verify device --recovery-key-stdin'.

• معنی: backup وجود دارد، اما این دستگاه هنوز به زنجیره cross-signing به اندازه کافی اعتماد ندارد.
• کار لازم: MATRIX_RECOVERY_KEY را set کنید و printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify device --recovery-key-stdin را اجرا کنید.

Matrix recovery key is required

• معنی: یک مرحله بازیابی را بدون ارائه recovery key اجرا کردید، در حالی که recovery key لازم بود.
• کار لازم: command را با --recovery-key-stdin دوباره اجرا کنید، برای مثال printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify device --recovery-key-stdin.

Invalid Matrix recovery key: ...

• معنی: کلید ارائه‌شده قابل parse نبود یا با format مورد انتظار مطابقت نداشت.
• کار لازم: با recovery key دقیق از کلاینت Matrix یا فایل recovery-key خود دوباره تلاش کنید.

Matrix recovery key was applied, but this device still lacks full Matrix identity trust.

• معنی: OmeniaClaw توانست recovery key را apply کند، اما Matrix هنوز full cross-signing identity trust را برای این دستگاه برقرار نکرده است. خروجی command را برای Recovery key accepted، Backup usable، Cross-signing verified و Device verified by owner بررسی کنید.
• کار لازم: OmeniaClaw matrix verify self را اجرا کنید، request را در یک کلاینت Matrix دیگر accept کنید، SAS را مقایسه کنید، و فقط وقتی مطابقت داشت yes را type کنید. command پیش از گزارش success منتظر full Matrix identity trust می‌ماند. فقط زمانی از printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing استفاده کنید که عمداً می‌خواهید cross-signing identity فعلی را جایگزین کنید.

Matrix key backup is not active on this device after loading from secret storage.

• معنی: secret storage یک backup session فعال روی این دستگاه ایجاد نکرد.
• کار لازم: ابتدا دستگاه را verify کنید، سپس با OmeniaClaw matrix verify backup status دوباره بررسی کنید.

Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'OmeniaClaw matrix verify device --recovery-key-stdin' first.

• معنی: این دستگاه تا زمانی که device verification کامل نشود، نمی‌تواند از secret storage restore کند.
• کار لازم: ابتدا printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify device --recovery-key-stdin را اجرا کنید.

پیام‌های نصب Plugin سفارشی

Matrix is installed from a custom path that no longer exists: ...

• معنی: record نصب Plugin شما به یک مسیر محلی اشاره می‌کند که دیگر وجود ندارد.
• کار لازم: با OmeniaClaw plugins install @OmeniaClaw/matrix دوباره نصب کنید، یا اگر از یک repo checkout اجرا می‌کنید، OmeniaClaw plugins install ./path/to/local/matrix-plugin.

اگر history رمزگذاری‌شده هنوز برنمی‌گردد

این بررسی‌ها را به ترتیب اجرا کنید:

OmeniaClaw matrix verify status --verboseOmeniaClaw matrix verify backup status --verboseprintf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify backup restore --recovery-key-stdin --verbose

اگر backup با موفقیت restore شد اما برخی roomهای قدیمی هنوز history ندارند، احتمالاً آن کلیدهای missing هرگز توسط Plugin قبلی backup نشده بودند.

اگر می‌خواهید برای پیام‌های آینده از نو شروع کنید

اگر از دست دادن history رمزگذاری‌شده قدیمیِ غیرقابل بازیابی را می‌پذیرید و فقط یک baseline تمیز backup برای ادامه می‌خواهید، این commandها را به ترتیب اجرا کنید:

OmeniaClaw matrix verify backup reset --yesOmeniaClaw matrix verify backup status --verboseOmeniaClaw matrix verify status

اگر پس از آن دستگاه هنوز unverified است، verification را از کلاینت Matrix خود با مقایسه emojiهای SAS یا decimal codeها کامل کنید و تأیید کنید که مطابقت دارند.

مرتبط

• Matrix: راه‌اندازی channel و config.
• Matrix push rules: مسیریابی notification.
• Doctor: health check و trigger خودکار migration.
• Migration guide: همه مسیرهای migration (جابه‌جایی machine، importهای cross-system).
• Plugins: نصب و registration پلاگین.