Maintenance
راهنمای مهاجرت
OpenClaw از سه مسیر مهاجرت پشتیبانی میکند: وارد کردن از یک سامانه عامل دیگر، انتقال نصب موجود به یک دستگاه جدید، و ارتقای یک Plugin در همان محل.
وارد کردن از یک سامانه عامل دیگر
از ارائهدهندگان مهاجرت همراه استفاده کنید تا دستورالعملها، سرورهای MCP، skills، پیکربندی مدل، و کلیدهای API (با انتخاب کاربر) را به OpenClaw بیاورید. طرحها پیش از هر تغییری پیشنمایش میشوند، اسرار در گزارشها پنهان میشوند، و اعمال تغییرات با یک نسخه پشتیبان تأییدشده پشتیبانی میشود.
وضعیت Claude Code و Claude Desktop را وارد کنید، از جمله CLAUDE.md، سرورهای MCP، skills، و فرمانهای پروژه.
پیکربندی Hermes، ارائهدهندگان، سرورهای MCP، حافظه، skills، و کلیدهای پشتیبانیشده .env را وارد کنید.
نقطه ورود CLI، openclaw migrate است. فرایند راهاندازی اولیه نیز میتواند وقتی یک منبع شناختهشده را تشخیص میدهد (openclaw onboard --flow import)، مهاجرت را پیشنهاد کند.
انتقال OpenClaw به یک دستگاه جدید
برای حفظ موارد زیر، دایرکتوری وضعیت (بهصورت پیشفرض ~/.openclaw/) و محیط کاری خود را کپی کنید:
- پیکربندی —
openclaw.jsonو همه تنظیمات gateway. - احراز هویت —
auth-profiles.jsonبرای هر عامل (کلیدهای API بههمراه OAuth)، بهعلاوه هر وضعیت کانال یا ارائهدهنده زیرcredentials/. - نشستها — تاریخچه گفتگو و وضعیت عامل.
- وضعیت کانال — ورود WhatsApp، نشست Telegram، و موارد مشابه.
- فایلهای محیط کاری —
MEMORY.md،USER.md، skills، و promptها.
مراحل مهاجرت
Stop the gateway and back up
روی دستگاه قدیمی، gateway را متوقف کنید تا فایلها هنگام کپی تغییر نکنند، سپس آرشیو بگیرید:
openclaw gateway stop
cd ~
tar -czf openclaw-state.tgz .openclaw
اگر از چند پروفایل استفاده میکنید (برای مثال ~/.openclaw-work)، هرکدام را جداگانه آرشیو کنید.
Install OpenClaw on the new machine
CLI (و در صورت نیاز Node) را روی دستگاه جدید نصب کنید. اگر راهاندازی اولیه یک ~/.openclaw/ تازه بسازد مشکلی نیست. در مرحله بعد آن را بازنویسی میکنید.
Copy state directory and workspace
آرشیو را از طریق scp، rsync -a، یا یک درایو خارجی منتقل کنید، سپس استخراج کنید:
cd ~
tar -xzf openclaw-state.tgz
مطمئن شوید دایرکتوریهای مخفی هم شامل شدهاند و مالکیت فایلها با کاربری که gateway را اجرا خواهد کرد مطابقت دارد.
Run doctor and verify
روی دستگاه جدید، برای اعمال مهاجرتهای پیکربندی و تعمیر سرویسها، Doctor را اجرا کنید:
openclaw doctor
openclaw gateway restart
openclaw status
اگر Telegram یا Discord از fallback پیشفرض env (TELEGRAM_BOT_TOKEN یا DISCORD_BOT_TOKEN) استفاده میکند، بدون چاپ مقدارهای محرمانه، بررسی کنید که .env دایرکتوری وضعیت مهاجرتدادهشده این کلیدها را دارد:
awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.openclaw/.env
openclaw doctor همچنین زمانی هشدار میدهد که یک حساب پیشفرض فعال Telegram یا Discord توکن پیکربندیشده نداشته باشد و متغیر env متناظر در دسترس فرایند doctor نباشد.
مشکلات رایج
Profile or state-dir mismatch
اگر gateway قدیمی از --profile یا OPENCLAW_STATE_DIR استفاده میکرد و gateway جدید این کار را نمیکند، کانالها بهصورت خارجشده از حساب دیده میشوند و نشستها خالی خواهند بود. gateway را با همان پروفایل یا دایرکتوری وضعیتی که مهاجرت دادهاید اجرا کنید، سپس دوباره openclaw doctor را اجرا کنید.
Copying only openclaw.json
فایل پیکربندی بهتنهایی کافی نیست. پروفایلهای احراز هویت مدل زیر agents/<agentId>/agent/auth-profiles.json قرار دارند، و وضعیت کانال و ارائهدهنده زیر credentials/ قرار دارد. همیشه کل دایرکتوری وضعیت را مهاجرت دهید.
Permissions and ownership
اگر با root کپی کردهاید یا کاربر را تغییر دادهاید، gateway ممکن است نتواند credentialها را بخواند. مطمئن شوید دایرکتوری وضعیت و محیط کاری متعلق به کاربری هستند که gateway را اجرا میکند.
Remote mode
اگر رابط کاربری شما به یک gateway راهدور اشاره میکند، میزبان راهدور مالک نشستها و محیط کاری است. خود میزبان gateway را مهاجرت دهید، نه لپتاپ محلی خود را. پرسشهای متداول را ببینید.
Secrets in backups
دایرکتوری وضعیت شامل پروفایلهای احراز هویت، credentialهای کانال، و وضعیت سایر ارائهدهندگان است. نسخههای پشتیبان را رمزنگاریشده نگه دارید، از کانالهای انتقال ناامن پرهیز کنید، و اگر به افشا شدن مشکوک هستید کلیدها را چرخش دهید.
فهرست بررسی تأیید
روی دستگاه جدید، تأیید کنید:
- [ ]
openclaw statusنشان میدهد gateway در حال اجرا است. - [ ] کانالها همچنان متصل هستند (نیازی به جفتسازی دوباره نیست).
- [ ] داشبورد باز میشود و نشستهای موجود را نشان میدهد.
- [ ] فایلهای محیط کاری (حافظه، پیکربندیها) وجود دارند.
ارتقای یک Plugin در همان محل
ارتقاهای درجا برای Plugin همان شناسه Plugin و کلیدهای پیکربندی را حفظ میکنند، اما ممکن است وضعیت روی دیسک را به چیدمان فعلی منتقل کنند. راهنماهای ارتقای مختص Plugin کنار کانالهای آنها قرار دارند:
- مهاجرت Matrix: محدودیتهای بازیابی وضعیت رمزنگاریشده، رفتار snapshot خودکار، و فرمانهای بازیابی دستی.
مرتبط
openclaw migrate: مرجع CLI برای وارد کردن بین سامانهها.- نمای کلی نصب: همه روشهای نصب.
- Doctor: بررسی سلامت پس از مهاجرت.
- حذف نصب: حذف پاکیزه OpenClaw.