---
read_when:
    - به‌روزرسانی OpenClaw
    - پس از به‌روزرسانی، چیزی از کار می‌افتد
summary: به‌روزرسانی ایمن OpenClaw (نصب سراسری یا از کد منبع)، به‌همراه راهبرد بازگشت به نسخهٔ پیشین
title: به‌روزرسانی
x-i18n:
    generated_at: "2026-07-12T10:17:33Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 06b475fcd715afa5f4b9fa3fc7d546ba8dc53805c6a29e12fd4706dceb04cb60
    source_path: install/updating.md
    workflow: 16
---

OpenClaw را به‌روز نگه دارید.

برای جایگزینی ایمیج‌ها در Docker، Podman و Kubernetes، به
[ارتقای ایمیج‌های کانتینر](/fa/install/docker#upgrading-container-images) مراجعه کنید. Gateway
پیش از آماده‌شدن، عملیات ارتقای ایمن هنگام راه‌اندازی را اجرا می‌کند و اگر وضعیت
مانت‌شده به تعمیر دستی نیاز داشته باشد، خارج می‌شود.

## توصیه‌شده: `openclaw update`

نوع نصب شما (npm یا git) را تشخیص می‌دهد، آخرین نسخه را دریافت می‌کند، `openclaw doctor` را اجرا می‌کند و Gateway را مجدداً راه‌اندازی می‌کند.

```bash
openclaw update
```

کانال‌ها را تغییر دهید یا نسخه مشخصی را هدف قرار دهید:

```bash
openclaw update --channel beta
openclaw update --channel extended-stable
openclaw update --channel dev
openclaw update --dry-run   # پیش‌نمایش بدون اعمال تغییرات
```

`openclaw update` پرچم `--verbose` ندارد (نصب‌کننده دارد). برای عیب‌یابی، از
`--dry-run` برای پیش‌نمایش عملیات برنامه‌ریزی‌شده، از `--json` برای نتایج ساخت‌یافته، یا از
`openclaw update status --json` برای بررسی وضعیت کانال و دسترس‌پذیری استفاده کنید.

`--channel beta` تگ توزیع beta در npm را ترجیح می‌دهد، اما اگر تگ beta موجود نباشد
یا نسخه آن قدیمی‌تر از آخرین انتشار پایدار باشد، به stable/latest برمی‌گردد.
برای به‌روزرسانی یک‌باره بسته که به تگ توزیع خام beta در npm مقید باشد، به‌جای آن
از `--tag beta` استفاده کنید.

`--channel extended-stable` فقط برای بسته‌هاست و نصب همچنان
فقط در پیش‌زمینه انجام می‌شود. OpenClaw انتخابگر عمومی `extended-stable` در npm را می‌خواند،
بسته دقیق انتخاب‌شده را تأیید می‌کند و همان نسخه دقیق را نصب می‌کند. نبودن
یا ناسازگاری داده‌های رجیستری باعث توقف ایمن می‌شود و هرگز به `latest` برنمی‌گردد.
اگر نسخه انتخاب‌شده قدیمی‌تر از نسخه نصب‌شده باشد، تأیید معمول
تنزل نسخه همچنان اعمال می‌شود. CLI پس از به‌روزرسانی موفق هسته، کانال را
ذخیره می‌کند؛ اجرای مستقیم `npm install -g openclaw@extended-stable`
مقدار `update.channel` را به‌روز نمی‌کند.
پس از تعویض هسته، Pluginهای رسمی واجد شرایط npm که قصد bare/default یا
`latest` دارند، با همان نسخه دقیق هسته همگرا می‌شوند. پین‌های دقیق و تگ‌های صریح
غیر از `latest`، Pluginهای شخص ثالث و منابع غیر npm بدون تغییر باقی می‌مانند.
نصب‌های کاتالوگ ایجادشده با نسخه‌های فعلی OpenClaw همان قصد پیش‌فرض را
حفظ می‌کنند. رکوردهای قدیمی‌تر که فقط شامل یک نسخه دقیق هستند، پین‌شده باقی می‌مانند، زیرا
OpenClaw نمی‌تواند با اطمینان یک پین خودکار قدیمی را از پین کاربر تشخیص دهد؛ برای
بازگرداندن آن Plugin به ردیابی دقیق هسته، یک‌بار در کانال extended-stable فرمان
`openclaw plugins update @openclaw/name` را اجرا کنید.

`--channel dev` یک checkout متحرک و پایدار از `main` در GitHub فراهم می‌کند. برای
به‌روزرسانی یک‌باره بسته، `--tag main` به مشخصه بسته
`github:openclaw/openclaw#main` نگاشت می‌شود و آن را مستقیماً از طریق مدیر بسته هدف
(npm/pnpm/bun) نصب می‌کند.

برای Pluginهای مدیریت‌شده، نبود انتشار beta یک هشدار است، نه خطا:
به‌روزرسانی هسته همچنان می‌تواند موفق شود، درحالی‌که Plugin به انتشار
default/latest ثبت‌شده خود برمی‌گردد.

برای معنای کانال‌ها، به [کانال‌های انتشار](/fa/install/development-channels) مراجعه کنید.

## جابه‌جایی بین نصب‌های npm و git

برای تغییر نوع نصب از کانال‌ها استفاده کنید. به‌روزرسان، وضعیت، پیکربندی،
اعتبارنامه‌ها و فضای کاری شما را در `~/.openclaw` حفظ می‌کند؛ فقط نصب کد OpenClaw
مورد استفاده CLI و Gateway را تغییر می‌دهد.

```bash
# نصب بسته npm -> checkout قابل‌ویرایش git
openclaw update --channel dev

# checkout گیت -> نصب بسته npm
openclaw update --channel stable
```

ابتدا تغییر حالت نصب را پیش‌نمایش کنید:

```bash
openclaw update --channel dev --dry-run
openclaw update --channel stable --dry-run
```

`dev` وجود یک checkout گیت را تضمین می‌کند، آن را می‌سازد و CLI سراسری را از همان
checkout نصب می‌کند. کانال‌های `stable`، `extended-stable` و `beta` از نصب
بسته استفاده می‌کنند. extended-stable روی checkout گیت، بدون تغییر یا
تبدیل آن، رد می‌شود. اگر Gateway از قبل نصب شده باشد، `openclaw update`
فراداده سرویس را تازه‌سازی و آن را مجدداً راه‌اندازی می‌کند، مگر اینکه `--no-restart` را ارسال کنید.

برای نصب‌های بسته‌ای دارای سرویس Gateway مدیریت‌شده، `openclaw update`
ریشه بسته مورد استفاده آن سرویس را هدف قرار می‌دهد. اگر فرمان `openclaw` در پوسته
از نصب دیگری آمده باشد، به‌روزرسان هر دو ریشه و مسیر Node سرویس
مدیریت‌شده را نمایش می‌دهد و پیش از جایگزینی بسته، نسخه Node را با الزام
`engines.node` انتشار هدف بررسی می‌کند.

## روش جایگزین: اجرای مجدد نصب‌کننده

```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```

برای رد کردن راه‌اندازی اولیه، `--no-onboard` را اضافه کنید. برای اجبار یک نوع نصب مشخص،
`--install-method git --no-onboard` یا `--install-method npm --no-onboard` را ارسال کنید.

اگر `openclaw update` پس از مرحله نصب بسته npm ناموفق بود، به‌جای آن
نصب‌کننده را دوباره اجرا کنید. نصب‌کننده به‌روزرسان را فراخوانی نمی‌کند؛ نصب سراسری بسته را
مستقیماً اجرا می‌کند و می‌تواند یک نصب npm نیمه‌به‌روزشده را بازیابی کند.

```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
```

با `--version` بازیابی را به نسخه یا تگ توزیع مشخصی مقید کنید:

```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
```

## روش جایگزین: npm، pnpm یا bun به‌صورت دستی

```bash
npm i -g openclaw@latest
```

برای نصب‌های تحت نظارت، `openclaw update` را ترجیح دهید: این فرمان می‌تواند تعویض بسته را
با سرویس در حال اجرای Gateway هماهنگ کند. اگر یک نصب تحت نظارت را به‌صورت دستی
به‌روز می‌کنید، ابتدا Gateway مدیریت‌شده را متوقف کنید. مدیران بسته فایل‌ها را
درجا جایگزین می‌کنند و در غیر این صورت، Gateway در حال اجرا ممکن است هنگام تعویض
برای بارگذاری فایل‌های هسته یا Plugin تلاش کند. پس از پایان کار مدیر بسته،
Gateway را مجدداً راه‌اندازی کنید تا نصب جدید را دریافت کند.

در نصب سراسری سیستمی Linux تحت مالکیت root، اگر `openclaw update` با خطای
`EACCES` مواجه شد، با npm سیستمی بازیابی کنید و هنگام جایگزینی دستی،
Gateway را متوقف نگه دارید. از همان پرچم‌های پروفایل/محیطی استفاده کنید که معمولاً برای
آن Gateway به کار می‌برید. `/usr/bin/npm` را با npm سیستمی که پیشوند سراسری
تحت مالکیت root را روی میزبان شما در اختیار دارد، جایگزین کنید:

```bash
openclaw gateway stop
sudo /usr/bin/npm i -g openclaw@latest
openclaw gateway install --force
openclaw gateway restart
```

سپس تأیید کنید:

```bash
openclaw --version
curl -fsS http://127.0.0.1:18789/readyz
openclaw plugins list --json
openclaw gateway status --deep --json
openclaw doctor --lint --json
```

وقتی `openclaw update` یک نصب سراسری npm را مدیریت می‌کند، ابتدا هدف را
در یک پیشوند موقت npm نصب می‌کند، موجودی بسته‌بندی‌شده `dist` را تأیید می‌کند، سپس
درخت تمیز بسته را به پیشوند سراسری واقعی منتقل می‌کند؛ در نتیجه از هم‌پوشانی
بسته جدید توسط npm روی فایل‌های باقی‌مانده از بسته قدیمی جلوگیری می‌شود. اگر فرمان
نصب ناموفق باشد، OpenClaw یک‌بار با `--omit=optional` دوباره تلاش می‌کند؛ این کار به
میزبان‌هایی کمک می‌کند که وابستگی‌های اختیاری بومی در آن‌ها قابل کامپایل نیستند.

فرمان‌های به‌روزرسانی npm و به‌روزرسانی Plugin که توسط OpenClaw مدیریت می‌شوند،
قرنطینه زنجیره تأمین `min-release-age` در npm (یا کلید پیکربندی قدیمی‌تر `before`) را نیز
برای فرایند فرزند npm پاک می‌کنند. این سیاست برای حفاظت عمومی وجود دارد، اما یک
به‌روزرسانی صریح OpenClaw یعنی «انتشار انتخاب‌شده را همین حالا نصب کن».

```bash
pnpm add -g openclaw@latest
```

```bash
bun add -g openclaw@latest
```

### موضوعات پیشرفته نصب npm

<AccordionGroup>
  <Accordion title="درخت بسته فقط‌خواندنی">
    OpenClaw نصب‌های سراسری بسته‌بندی‌شده را هنگام اجرا فقط‌خواندنی در نظر می‌گیرد، حتی اگر پوشه سراسری بسته برای کاربر فعلی قابل نوشتن باشد. نصب بسته‌های Plugin در ریشه‌های npm/git تحت مالکیت OpenClaw در پوشه پیکربندی کاربر قرار می‌گیرد و راه‌اندازی Gateway درخت بسته OpenClaw را تغییر نمی‌دهد.

    برخی تنظیمات npm در Linux بسته‌های سراسری را در پوشه‌های تحت مالکیت root مانند `/usr/lib/node_modules/openclaw` نصب می‌کنند. OpenClaw از این چیدمان پشتیبانی می‌کند، زیرا فرمان‌های نصب/به‌روزرسانی Plugin خارج از آن پوشه سراسری بسته می‌نویسند.

  </Accordion>
  <Accordion title="واحدهای مقاوم‌سازی‌شده systemd">
    به OpenClaw دسترسی نوشتن در ریشه‌های پیکربندی/وضعیت خود بدهید تا نصب‌های صریح Plugin، به‌روزرسانی‌های Plugin و پاک‌سازی doctor بتوانند تغییراتشان را ذخیره کنند:

    ```ini
    ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
    ```

  </Accordion>
  <Accordion title="بررسی اولیه فضای دیسک">
    پیش از به‌روزرسانی بسته‌ها و نصب‌های صریح Plugin، OpenClaw تلاش می‌کند فضای دیسک حجم هدف را به‌صورت بهترین‌تلاش بررسی کند. فضای کم هشداری همراه با مسیر بررسی‌شده ایجاد می‌کند، اما به‌روزرسانی را مسدود نمی‌کند، زیرا سهمیه‌های فایل‌سیستم، snapshotها و حجم‌های شبکه ممکن است پس از بررسی تغییر کنند. نصب واقعی مدیر بسته و تأیید پس از نصب همچنان ملاک نهایی هستند.
  </Accordion>
</AccordionGroup>

## به‌روزرسان خودکار

به‌طور پیش‌فرض خاموش است. آن را در `~/.openclaw/openclaw.json` فعال کنید:

```json5
{
  update: {
    channel: "stable",
    auto: {
      enabled: true,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}
```

| کانال             | رفتار                                                                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stable`          | به‌اندازه `stableDelayHours` (پیش‌فرض: 6) منتظر می‌ماند، سپس با تأخیر تصادفی قطعی در بازه `stableJitterHours` (پیش‌فرض: 12) برای انتشار تدریجی اعمال می‌کند. |
| `extended-stable` | هنگام راه‌اندازی و در صورت فعال بودن `checkOnStart`، هر 24 ساعت یک‌بار وجود راهنمای فقط‌خواندنی به‌روزرسانی را بررسی می‌کند. هرگز خودکار اعمال نمی‌کند.      |
| `beta`            | هر `betaCheckIntervalHours` ساعت (پیش‌فرض: 1) بررسی می‌کند و بلافاصله اعمال می‌کند.                                                                       |
| `dev`             | اعمال خودکار ندارد. `openclaw update` را به‌صورت دستی استفاده کنید.                                                                                     |

Gateway همچنین هنگام راه‌اندازی یک راهنمای به‌روزرسانی ثبت می‌کند (با
`update.checkOnStart: false` غیرفعال کنید). انتخاب‌های ذخیره‌شده extended-stable از همین
مسیر راهنمای فقط‌خواندنی و فاصله زمانی موجود 24ساعته استفاده می‌کنند، اما هرگز
نصب خودکار، واگذاری، راه‌اندازی مجدد، تأخیر/نوسان stable یا نظرسنجی beta را فراخوانی نمی‌کنند.
برای تنزل نسخه یا بازیابی پس از رخداد، `OPENCLAW_NO_AUTO_UPDATE=1` را در محیط Gateway تنظیم کنید تا حتی در صورت پیکربندی `update.auto.enabled` نیز اعمال خودکار مسدود شود. راهنماهای به‌روزرسانی هنگام راه‌اندازی همچنان می‌توانند اجرا شوند، مگر اینکه `update.checkOnStart` نیز غیرفعال باشد.

به‌روزرسانی‌های مدیر بسته که از طریق صفحه کنترل زنده Gateway
(`update.run`) درخواست می‌شوند، درخت بسته را درون فرایند در حال اجرای Gateway
جایگزین نمی‌کنند. در نصب‌های سرویس مدیریت‌شده، Gateway یک واگذاری جداشده را آغاز می‌کند،
خارج می‌شود و به مسیر عادی CLI یعنی `openclaw update --yes --json` اجازه می‌دهد
سرویس را متوقف کند، بسته را جایگزین کند، فراداده سرویس را تازه‌سازی کند، دوباره راه‌اندازی کند،
نسخه و دسترس‌پذیری Gateway را تأیید کند و در صورت امکان، LaunchAgent نصب‌شده اما
بارگذاری‌نشده macOS را بازیابی کند. اگر Gateway نتواند این واگذاری را با ایمنی انجام دهد،
`update.run` به‌جای اجرای درون‌فرایندی مدیر بسته، یک فرمان امن پوسته گزارش می‌کند.

کارت به‌روزرسانی نوار کناری رابط کنترل، همین جریان `update.run` را آغاز می‌کند. در
برنامه امضاشده macOS، کارت ابتدا برنامه را از طریق Sparkle به‌روز می‌کند؛ پس از اجرای مجدد،
برنامه Gateway محلی مدیریت‌شده خود را به نسخه منطبق می‌رساند.

## پس از به‌روزرسانی

<Steps>

### اجرای doctor

```bash
openclaw doctor
```

پیکربندی را مهاجرت می‌دهد، سیاست‌های پیام مستقیم را ممیزی می‌کند و سلامت Gateway را بررسی می‌کند. جزئیات: [Doctor](/fa/gateway/doctor)

### راه‌اندازی مجدد Gateway

```bash
openclaw gateway restart
```

### تأیید

```bash
openclaw health
```

</Steps>

## بازگردانی

### پین‌کردن یک نسخه (npm)

```bash
npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart
```

<Tip>
`npm view openclaw version` نسخه منتشرشده فعلی را نشان می‌دهد.
</Tip>

### پین‌کردن یک commit (منبع)

```bash
git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
pnpm install && pnpm build
openclaw gateway restart
```

برای بازگشت به آخرین نسخه: `git checkout main && git pull`.

## اگر به مشکل برخوردید

- `openclaw doctor` را دوباره اجرا کنید و خروجی را با دقت بخوانید.
- برای `openclaw update --channel dev` روی checkoutهای منبع، به‌روزرسان در صورت نیاز `pnpm` را به‌طور خودکار راه‌اندازی می‌کند. اگر خطای راه‌اندازی pnpm/corepack را مشاهده کردید، `pnpm` را به‌صورت دستی نصب کنید (یا `corepack` را دوباره فعال کنید) و به‌روزرسانی را دوباره اجرا کنید.
- بررسی کنید: [عیب‌یابی](/fa/gateway/troubleshooting)
- در Discord بپرسید: [https://discord.gg/clawd](https://discord.gg/clawd)

## مرتبط

- [نمای کلی نصب](/fa/install): همه روش‌های نصب.
- [عیب‌یابی](/fa/gateway/doctor): بررسی‌های سلامت پس از به‌روزرسانی‌ها.
- [مهاجرت](/fa/install/migrating): راهنماهای مهاجرت به نسخه‌های اصلی جدید.