Mainstream messaging

مهاجرت Matrix

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

OpenClaw و Plugin مربوط به Matrix را به‌طور معمول به‌روزرسانی کنید. openclaw update ساده را بدون --no-restart ترجیح دهید تا شروع به کار بتواند مهاجرت Matrix را بلافاصله کامل کند.
اجرا کنید:
```
openclaw doctor --fix
```
اگر Matrix کار مهاجرت قابل‌اقدام داشته باشد، doctor ابتدا اسنپ‌شات پیش از مهاجرت را ایجاد می‌کند یا از آن دوباره استفاده می‌کند و مسیر آرشیو را چاپ می‌کند.
Gateway را شروع یا دوباره راه‌اندازی کنید.
وضعیت فعلی راستی‌آزمایی و پشتیبان را بررسی کنید:
```
openclaw matrix verify status
openclaw matrix verify backup status
```
کلید بازیابی حساب Matrix را که در حال ترمیم آن هستید در یک متغیر محیطی مخصوص حساب قرار دهید. برای یک حساب پیش‌فرض واحد، MATRIX_RECOVERY_KEY کافی است. برای چند حساب، برای هر حساب یک متغیر استفاده کنید، برای مثال MATRIX_RECOVERY_KEY_ASSISTANT، و --account assistant را به فرمان اضافه کنید.

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

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

اگر این دستگاه هنوز راستی‌آزمایی نشده است، فرمان را برای حساب متناظر اجرا کنید:
```
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify device --recovery-key-stdin --account assistant
```
اگر کلید بازیابی پذیرفته شد و پشتیبان قابل استفاده بود، اما Cross-signing verified هنوز no است، خودراستی‌آزمایی را از یک کلاینت Matrix دیگر کامل کنید:
```
openclaw matrix verify self
```
درخواست را در یک کلاینت Matrix دیگر بپذیرید، ایموجی یا اعداد اعشاری را مقایسه کنید، و فقط وقتی مطابقت دارند yes را تایپ کنید. فرمان فقط پس از آنکه Cross-signing verified به yes تبدیل شود با موفقیت خارج می‌شود.
اگر عمدا تاریخچه قدیمی غیرقابل‌بازیابی را کنار می‌گذارید و برای پیام‌های آینده یک خط پایه پشتیبان تازه می‌خواهید، اجرا کنید:
```
openclaw matrix verify backup reset --yes
```
اگر هنوز هیچ پشتیبان کلید سمت سرور وجود ندارد، برای بازیابی‌های آینده یکی بسازید:
```
openclaw matrix verify bootstrap
```

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

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

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

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

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

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

Matrix plugin upgraded in place.

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

Matrix migration snapshot created before applying Matrix upgrades.

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

Matrix migration snapshot reused before applying Matrix upgrades.

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

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

معنی: وضعیت قدیمی Matrix وجود دارد، اما OpenClaw نمی‌تواند آن را به یک حساب Matrix فعلی نگاشت کند، چون Matrix پیکربندی نشده است.
چه باید کرد: channels.matrix را پیکربندی کنید، سپس openclaw 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...).

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

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

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

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

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

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

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

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

معنی: OpenClaw یک ذخیره‌گاه رمزگذاری‌شده قدیمی Matrix پیدا کرد، اما هیچ پیکربندی فعلی Matrix برای اتصال آن وجود ندارد.
چه باید کرد: channels.matrix را پیکربندی کنید، سپس openclaw 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...).

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

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

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

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

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

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

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

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

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

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

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

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

Failed migrating legacy Matrix client storage: ...

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

Matrix is installed from a custom path: ...

معنی: Matrix به یک نصب مبتنی بر مسیر pin شده است، بنابراین به‌روزرسانی‌های mainline به‌طور خودکار آن را با package استاندارد Matrix در repo جایگزین نمی‌کنند.
کار لازم: وقتی می‌خواهید به Plugin پیش‌فرض Matrix برگردید، با openclaw plugins install @openclaw/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 "openclaw matrix verify backup restore --recovery-key-stdin" after upgrade if they have the recovery key.

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

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

معنی: OpenClaw store رمزگذاری‌شده قدیمی را پیدا کرد، اما نتوانست آن را به اندازه کافی امن بررسی کند تا بازیابی را آماده کند.
کار لازم: openclaw doctor --fix را دوباره اجرا کنید. اگر تکرار شد، دایرکتوری وضعیت قدیمی را دست‌نخورده نگه دارید و با استفاده از یک کلاینت Matrix verified دیگر به‌همراه printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw 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.

معنی: OpenClaw یک تداخل 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 خطا برگرداند.
کار لازم: openclaw matrix verify backup status را اجرا کنید، سپس در صورت نیاز با printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin دوباره تلاش کنید.

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

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

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

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

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

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

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

اگر از دست دادن history رمزگذاری‌شده قدیمیِ غیرقابل بازیابی را می‌پذیرید، می‌توانید در عوض baseline فعلی backup را با openclaw 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 'openclaw matrix verify device --recovery-key-stdin'.

معنی: backup وجود دارد، اما این دستگاه هنوز به زنجیره cross-signing به اندازه کافی اعتماد ندارد.
کار لازم: MATRIX_RECOVERY_KEY را set کنید و printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw 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" | openclaw 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.

معنی: OpenClaw توانست recovery key را apply کند، اما Matrix هنوز full cross-signing identity trust را برای این دستگاه برقرار نکرده است. خروجی command را برای Recovery key accepted، Backup usable، Cross-signing verified و Device verified by owner بررسی کنید.
کار لازم: openclaw matrix verify self را اجرا کنید، request را در یک کلاینت Matrix دیگر accept کنید، SAS را مقایسه کنید، و فقط وقتی مطابقت داشت yes را type کنید. command پیش از گزارش success منتظر full Matrix identity trust می‌ماند. فقط زمانی از printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw 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 کنید، سپس با openclaw matrix verify backup status دوباره بررسی کنید.

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

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

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

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

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

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

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

openclaw matrix verify status --verbose
openclaw matrix verify backup status --verbose
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin --verbose

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

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

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

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw 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 پلاگین.

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

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

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

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

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

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

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

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

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

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

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

# مرتبط