---
read_when:
    - در حال انتقال OpenClaw به یک لپ‌تاپ یا سرور جدید هستید
    - از سامانه عامل دیگری می‌آیید و می‌خواهید وضعیت را حفظ کنید
    - در حال ارتقای یک Plugin در محل هستید
summary: 'مرکز مهاجرت: واردسازی‌های بین‌سیستمی، انتقال‌های ماشین‌به‌ماشین و ارتقای Pluginها'
title: راهنمای مهاجرت
x-i18n:
    generated_at: "2026-07-27T16:42:05Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: e9ceb80045ab082c9cfc9e1aca59e079b6bf28b1d047265a0be40c03ebe5dac6
    source_path: install/migrating.md
    workflow: 16
---

OpenClaw از سه مسیر مهاجرت پشتیبانی می‌کند: واردکردن از یک سامانه عامل دیگر، انتقال نصب موجود به یک دستگاه جدید، و ارتقای درجا یک Plugin.

## واردکردن از یک سامانه عامل دیگر

ارائه‌دهندگان مهاجرت همراه، دستورالعمل‌ها، سرورهای MCP، مهارت‌ها، پیکربندی مدل و کلیدهای API (به‌صورت اختیاری) را به OpenClaw منتقل می‌کنند. پیش از هر تغییری، پیش‌نمایش طرح‌ها نمایش داده می‌شود و اطلاعات محرمانه در گزارش‌ها پوشانده می‌شوند. `openclaw migrate` مستقل به یک نسخه پشتیبان تأییدشده متکی است؛ در عوض، راه‌اندازی اولیه جدید، مصنوعات محلی را پیش از انتشار آماده و تأیید می‌کند و پیکربندی را پیش از هرگونه فعال‌سازی خارجی برگشت‌ناپذیر ثبت می‌کند.

<CardGroup cols={2}>
  <Card title="مهاجرت از Claude" href="/fa/install/migrating-claude" icon="brain">
    وضعیت Claude Code و Claude Desktop، از جمله `CLAUDE.md`، سرورهای MCP، مهارت‌ها و فرمان‌های پروژه را وارد کنید.
  </Card>
  <Card title="مهاجرت از Hermes" href="/fa/install/migrating-hermes" icon="feather">
    پیکربندی Hermes، ارائه‌دهندگان، سرورهای MCP، حافظه، مهارت‌ها و کلیدهای پشتیبانی‌شده `.env` را وارد کنید.
  </Card>
</CardGroup>

نقطه ورود CLI، [`openclaw migrate`](/fa/cli/migrate) است. راه‌اندازی اولیه نیز می‌تواند هنگام شناسایی یک منبع شناخته‌شده (`openclaw onboard --flow import`) مهاجرت را پیشنهاد دهد.

## انتقال OpenClaw به یک دستگاه جدید

برای حفظ موارد زیر، **دایرکتوری وضعیت** (به‌طور پیش‌فرض `~/.openclaw/`) و **فضای کاری** خود را کپی کنید:

- **پیکربندی** — `openclaw.json` و همه تنظیمات Gateway.
- **احراز هویت** — `auth-profiles.json` مختص هر عامل (کلیدهای API به‌همراه OAuth) و هرگونه وضعیت کانال یا ارائه‌دهنده در `credentials/`.
- **نشست‌ها** — تاریخچه مکالمه و وضعیت عامل.
- **وضعیت کانال** — ورود WhatsApp، نشست Telegram و موارد مشابه.
- **فایل‌های فضای کاری** — `MEMORY.md`، `USER.md`، مهارت‌ها و پرامپت‌ها.

<Tip>
برای تأیید مسیر دایرکتوری وضعیت، `openclaw status` را روی دستگاه قدیمی اجرا کنید. پروفایل‌های سفارشی از `~/.openclaw-<profile>/` یا مسیری که از طریق `OPENCLAW_STATE_DIR` تنظیم شده است استفاده می‌کنند.
</Tip>

### مراحل مهاجرت

<Steps>
  <Step title="توقف Gateway و تهیه نسخه پشتیبان">
    در دستگاه **قدیمی**، Gateway را متوقف کنید تا فایل‌ها هنگام کپی تغییر نکنند، سپس بایگانی تهیه کنید:

    ```bash
    openclaw gateway stop
    cd ~
    tar -czf openclaw-state.tgz .openclaw
    ```

    اگر از چند پروفایل استفاده می‌کنید (برای مثال `~/.openclaw-work`)، هرکدام را جداگانه بایگانی کنید.

  </Step>

  <Step title="نصب OpenClaw روی دستگاه جدید">
    CLI (و در صورت نیاز Node) را روی دستگاه جدید [نصب کنید](/fa/install). اگر راه‌اندازی اولیه یک `~/.openclaw/` جدید ایجاد کند، مشکلی نیست؛ در مرحله بعد آن را بازنویسی می‌کنید.
  </Step>

  <Step title="کپی دایرکتوری وضعیت و فضای کاری">
    بایگانی را از طریق `scp`، `rsync -a` یا یک درایو خارجی منتقل و سپس استخراج کنید:

    ```bash
    cd ~
    tar -xzf openclaw-state.tgz
    ```

    تأیید کنید که دایرکتوری‌های مخفی نیز گنجانده شده‌اند و مالکیت فایل‌ها با کاربری که Gateway را اجرا خواهد کرد مطابقت دارد.

  </Step>

  <Step title="اجرای Doctor و تأیید">
    در دستگاه جدید، برای اعمال مهاجرت‌های پیکربندی و تعمیر سرویس‌ها، [Doctor](/fa/gateway/doctor) را اجرا کنید:

    ```bash
    openclaw doctor
    openclaw gateway restart
    openclaw status
    ```

  </Step>
</Steps>

اگر Telegram یا Discord از جایگزین پیش‌فرض متغیر محیطی (`TELEGRAM_BOT_TOKEN` یا `DISCORD_BOT_TOKEN`) استفاده می‌کند، بدون چاپ مقادیر محرمانه بررسی کنید که `.env` در دایرکتوری وضعیت مهاجرت‌داده‌شده حاوی این کلیدها باشد:

```bash
awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.openclaw/.env
```

`openclaw doctor` همچنین هنگامی هشدار می‌دهد که یک حساب پیش‌فرض فعال Telegram یا Discord توکن پیکربندی‌شده‌ای نداشته باشد و متغیر محیطی متناظر نیز در دسترس فرایند Doctor نباشد.

### خطاهای رایج

<AccordionGroup>
  <Accordion title="عدم تطابق پروفایل یا دایرکتوری وضعیت">
    اگر Gateway قدیمی از `--profile` یا `OPENCLAW_STATE_DIR` استفاده می‌کرد اما نمونه جدید استفاده نمی‌کند، کانال‌ها خارج‌شده از حساب به نظر می‌رسند و نشست‌ها خالی خواهند بود. Gateway را با **همان** پروفایل یا دایرکتوری وضعیتی که مهاجرت داده‌اید راه‌اندازی کنید، سپس `openclaw doctor` را دوباره اجرا کنید.
  </Accordion>

  <Accordion title="کپی‌کردن فقط openclaw.json">
    فایل پیکربندی به‌تنهایی کافی نیست. پروفایل‌های احراز هویت مدل در `agents/<agentId>/agent/auth-profiles.json` و وضعیت کانال و ارائه‌دهنده در `credentials/` قرار دارند. همیشه **کل** دایرکتوری وضعیت را مهاجرت دهید.
  </Accordion>

  <Accordion title="مجوزها و مالکیت">
    اگر فایل‌ها را با کاربر root کپی کرده‌اید یا کاربر را تغییر داده‌اید، ممکن است Gateway نتواند اطلاعات اعتبارسنجی را بخواند. مطمئن شوید دایرکتوری وضعیت و فضای کاری متعلق به کاربری هستند که Gateway را اجرا می‌کند.
  </Accordion>

  <Accordion title="حالت راه دور">
    اگر رابط کاربری شما به یک Gateway **راه دور** متصل است، نشست‌ها و فضای کاری متعلق به میزبان راه دور هستند. خود میزبان Gateway را مهاجرت دهید، نه لپ‌تاپ محلی خود را. به [پرسش‌های متداول](/fa/help/faq#where-things-live-on-disk) مراجعه کنید.
  </Accordion>

  <Accordion title="اطلاعات محرمانه در نسخه‌های پشتیبان">
    دایرکتوری وضعیت شامل پروفایل‌های احراز هویت، اطلاعات اعتبارسنجی کانال و سایر وضعیت‌های ارائه‌دهنده است. نسخه‌های پشتیبان را به‌صورت رمزگذاری‌شده نگه دارید، از کانال‌های انتقال ناامن اجتناب کنید و اگر به افشای اطلاعات مشکوک هستید، کلیدها را تعویض کنید.
  </Accordion>
</AccordionGroup>

### فهرست بررسی تأیید

در دستگاه جدید، موارد زیر را تأیید کنید:

- [ ] `openclaw status` نشان می‌دهد Gateway در حال اجرا است.
- [ ] کانال‌ها همچنان متصل هستند (نیازی به جفت‌سازی مجدد نیست).
- [ ] داشبورد باز می‌شود و نشست‌های موجود را نمایش می‌دهد.
- [ ] فایل‌های فضای کاری (حافظه و پیکربندی‌ها) موجود هستند.

## ارتقای درجا یک Plugin

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

- [مهاجرت Matrix](/fa/channels/matrix-migration): محدودیت‌های بازیابی وضعیت رمزگذاری‌شده، رفتار عکس فوری خودکار و فرمان‌های بازیابی دستی.

## مرتبط

- [`openclaw migrate`](/fa/cli/migrate): مرجع CLI برای واردکردن میان سامانه‌ها.
- [نمای کلی نصب](/fa/install): همه روش‌های نصب.
- [Doctor](/fa/gateway/doctor): بررسی سلامت پس از مهاجرت.
- [حذف نصب](/fa/install/uninstall): حذف کامل OpenClaw.
