---
read_when:
    - می‌خواهید یک نسخهٔ کاری منبع را به‌صورت ایمن به‌روزرسانی کنید
    - شما خروجی یا گزینه‌های `openclaw update` را اشکال‌زدایی می‌کنید
    - باید رفتار کوتاه‌نویسی `--update` را درک کنید
summary: مرجع CLI برای `openclaw update` (به‌روزرسانی نسبتاً ایمن منبع + راه‌اندازی مجدد خودکار Gateway)
title: به‌روزرسانی
x-i18n:
    generated_at: "2026-05-12T08:46:15Z"
    model: gpt-5.5
    provider: openai
    source_hash: 93244af800aaa53c55a52f9593a7727910aa91acac9d1e34e89c39a95b133461
    source_path: cli/update.md
    workflow: 16
---

# `openclaw update`

OpenClaw را با ایمنی به‌روزرسانی کنید و بین کانال‌های پایدار/بتا/توسعه جابه‌جا شوید.

اگر از طریق **npm/pnpm/bun** نصب کرده‌اید (نصب سراسری، بدون فراداده git)،
به‌روزرسانی‌ها از طریق جریان مدیر بسته در [به‌روزرسانی](/fa/install/updating) انجام می‌شوند.

## استفاده

```bash
openclaw update
openclaw update status
openclaw update wizard
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --tag main
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --json
openclaw --update
```

## گزینه‌ها

- `--no-restart`: از راه‌اندازی مجدد سرویس Gateway پس از به‌روزرسانی موفق صرف‌نظر می‌کند. به‌روزرسانی‌های مدیر بسته که Gateway را راه‌اندازی مجدد می‌کنند، پیش از موفق شدن فرمان، بررسی می‌کنند که سرویس راه‌اندازی‌شدهٔ مجدد نسخهٔ به‌روزرسانی‌شدهٔ مورد انتظار را گزارش کند.
- `--channel <stable|beta|dev>`: کانال به‌روزرسانی را تنظیم می‌کند (git + npm؛ در پیکربندی پایدار می‌شود).
- `--tag <dist-tag|version|spec>`: هدف بسته را فقط برای همین به‌روزرسانی بازنویسی می‌کند. برای نصب‌های بسته‌ای، `main` به `github:openclaw/openclaw#main` نگاشت می‌شود.
- `--dry-run`: اقدامات برنامه‌ریزی‌شدهٔ به‌روزرسانی (جریان کانال/برچسب/هدف/راه‌اندازی مجدد) را بدون نوشتن پیکربندی، نصب، همگام‌سازی پلاگین‌ها، یا راه‌اندازی مجدد پیش‌نمایش می‌کند.
- `--json`: JSON قابل‌خواندن برای ماشین از نوع `UpdateRunResult` را چاپ می‌کند، شامل
  `postUpdate.plugins.warnings` زمانی که پلاگین‌های مدیریت‌شدهٔ خراب یا غیرقابل بارگذاری پس از
  موفقیت به‌روزرسانی هسته نیاز به تعمیر دارند، جزئیات بازگشت پلاگین در کانال بتا
  زمانی که یک پلاگین انتشار بتا ندارد، و `postUpdate.plugins.integrityDrifts`
  زمانی که طی همگام‌سازی پلاگین پس از به‌روزرسانی، انحراف مصنوع بستهٔ npm پلاگین شناسایی شود.
- `--timeout <seconds>`: مهلت زمانی برای هر گام (پیش‌فرض 1800 ثانیه است).
- `--yes`: اعلان‌های تأیید را رد می‌کند (برای مثال تأیید بازگشت به نسخهٔ قدیمی‌تر).

`openclaw update` پرچم `--verbose` ندارد. برای پیش‌نمایش اقدامات
برنامه‌ریزی‌شدهٔ کانال/برچسب/نصب/راه‌اندازی مجدد از `--dry-run`، برای نتایج
قابل‌خواندن برای ماشین از `--json`، و زمانی که فقط به جزئیات کانال و
دسترس‌پذیری نیاز دارید از `openclaw update status --json` استفاده کنید. اگر
لاگ‌های Gateway را پیرامون یک به‌روزرسانی اشکال‌زدایی می‌کنید، سطح جزئیات کنسول
و سطح لاگ فایل جدا هستند: `--verbose` در Gateway خروجی ترمینال/WebSocket را
تحت تأثیر قرار می‌دهد، در حالی که لاگ‌های فایل به `logging.level: "debug"` یا
`"trace"` در پیکربندی نیاز دارند. [لاگ‌گیری Gateway](/fa/gateway/logging) را ببینید.

<Note>
در حالت Nix (`OPENCLAW_NIX_MODE=1`)، اجرای تغییردهندهٔ `openclaw update` غیرفعال است. به‌جای آن منبع Nix یا ورودی flake را برای این نصب به‌روزرسانی کنید؛ برای nix-openclaw، از [شروع سریع](https://github.com/openclaw/nix-openclaw#quick-start) عامل‌محور استفاده کنید. `openclaw update status` و `openclaw update --dry-run` همچنان فقط‌خواندنی باقی می‌مانند.
</Note>

<Warning>
بازگشت به نسخه‌های قدیمی‌تر به تأیید نیاز دارد، چون نسخه‌های قدیمی‌تر می‌توانند پیکربندی را خراب کنند.
</Warning>

## `update status`

کانال به‌روزرسانی فعال + برچسب/شاخه/SHA مربوط به git (برای checkoutهای منبع) را همراه با دسترس‌پذیری به‌روزرسانی نشان می‌دهد.

```bash
openclaw update status
openclaw update status --json
openclaw update status --timeout 10
```

گزینه‌ها:

- `--json`: JSON وضعیت قابل‌خواندن برای ماشین را چاپ می‌کند.
- `--timeout <seconds>`: مهلت زمانی برای بررسی‌ها (پیش‌فرض 3 ثانیه است).

## `update wizard`

جریان تعاملی برای انتخاب کانال به‌روزرسانی و تأیید اینکه آیا Gateway پس از
به‌روزرسانی راه‌اندازی مجدد شود یا نه (پیش‌فرض راه‌اندازی مجدد است). اگر `dev`
را بدون checkout از git انتخاب کنید، پیشنهاد می‌کند یکی ایجاد کند.

گزینه‌ها:

- `--timeout <seconds>`: مهلت زمانی برای هر گام به‌روزرسانی (پیش‌فرض `1800`)

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

وقتی کانال‌ها را صریحاً عوض می‌کنید (`--channel ...`)، OpenClaw روش نصب را نیز
هم‌راستا نگه می‌دارد:

- `dev` → وجود یک checkout از git را تضمین می‌کند (پیش‌فرض: `~/openclaw`، قابل بازنویسی با `OPENCLAW_GIT_DIR`)،
  آن را به‌روزرسانی می‌کند، و CLI سراسری را از همان checkout نصب می‌کند.
- `stable` → از npm با استفاده از `latest` نصب می‌کند.
- `beta` → dist-tag ‏`beta` در npm را ترجیح می‌دهد، اما وقتی بتا
  موجود نباشد یا از انتشار پایدار فعلی قدیمی‌تر باشد به `latest` برمی‌گردد.

به‌روزرسان خودکار هستهٔ Gateway (وقتی از طریق پیکربندی فعال شده باشد) مسیر
به‌روزرسانی CLI را بیرون از handler درخواست زندهٔ Gateway اجرا می‌کند. به‌روزرسانی‌های
مدیر بستهٔ `update.run` در صفحهٔ کنترل، پس از جابه‌جایی بسته، راه‌اندازی مجدد
به‌روزرسانی بدون تعویق و بدون دورهٔ خنک‌سازی را اجباری می‌کنند، زیرا فرایند
قدیمی Gateway ممکن است هنوز قطعه‌هایی در حافظه داشته باشد که به فایل‌های حذف‌شده
توسط بستهٔ جدید اشاره می‌کنند.

برای نصب‌های مدیر بسته، `openclaw update` پیش از فراخوانی مدیر بسته نسخهٔ بستهٔ
هدف را resolve می‌کند. نصب‌های سراسری npm از نصب مرحله‌بندی‌شده استفاده می‌کنند:
OpenClaw بستهٔ جدید را در یک پیشوند موقت npm نصب می‌کند، موجودی `dist` بسته‌بندی‌شده
را در آنجا بررسی می‌کند، سپس آن درخت بستهٔ پاک را به پیشوند سراسری واقعی جابه‌جا
می‌کند. اگر راستی‌آزمایی شکست بخورد، doctor پس از به‌روزرسانی، همگام‌سازی
پلاگین، و کار راه‌اندازی مجدد از درخت مشکوک اجرا نمی‌شوند. حتی وقتی نسخهٔ
نصب‌شده از قبل با هدف برابر باشد، فرمان نصب بستهٔ سراسری را نوسازی می‌کند،
سپس همگام‌سازی پلاگین، نوسازی تکمیل فرمان هسته، و کار راه‌اندازی مجدد را اجرا
می‌کند. این کار sidecarهای بسته‌بندی‌شده و رکوردهای پلاگین متعلق به کانال را
با build نصب‌شدهٔ OpenClaw هم‌راستا نگه می‌دارد، در حالی که بازسازی کامل تکمیل
فرمان پلاگین را به اجرای صریح `openclaw completion --write-state` واگذار می‌کند.

وقتی یک سرویس Gateway مدیریت‌شدهٔ محلی نصب باشد و راه‌اندازی مجدد فعال باشد،
به‌روزرسانی‌های مدیر بسته پیش از جایگزینی درخت بسته، سرویس در حال اجرا را متوقف
می‌کنند، سپس فرادادهٔ سرویس را از نصب به‌روزرسانی‌شده نوسازی می‌کنند، سرویس را
راه‌اندازی مجدد می‌کنند، و پیش از گزارش موفقیت بررسی می‌کنند که Gateway
راه‌اندازی‌شدهٔ مجدد نسخهٔ مورد انتظار را گزارش کند. در macOS، بررسی پس از
به‌روزرسانی همچنین بررسی می‌کند که LaunchAgent برای نمایهٔ فعال بارگذاری/در حال
اجرا باشد و پورت loopback پیکربندی‌شده سالم باشد. اگر plist نصب شده باشد اما
launchd بر آن نظارت نکند، OpenClaw به‌طور خودکار LaunchAgent را دوباره bootstrap
می‌کند، سپس بررسی‌های آمادگی سلامت/نسخه/کانال را دوباره اجرا می‌کند. یک bootstrap
تازه job مربوط به RunAtLoad را مستقیماً بارگذاری می‌کند، بنابراین بازیابی
به‌روزرسانی فوراً Gateway تازه ایجادشده را `kickstart -k` نمی‌کند. اگر Gateway
هنوز سالم نشود، فرمان با کد غیرصفر خارج می‌شود و مسیر لاگ راه‌اندازی مجدد را
همراه با دستورالعمل‌های صریح راه‌اندازی مجدد، نصب دوباره، و بازگردانی بسته چاپ
می‌کند. با `--no-restart`، جایگزینی بسته همچنان اجرا می‌شود اما سرویس مدیریت‌شده
متوقف یا راه‌اندازی مجدد نمی‌شود، بنابراین Gateway در حال اجرا ممکن است تا وقتی
آن را دستی راه‌اندازی مجدد نکنید، کد قدیمی را نگه دارد.

## جریان checkout از Git

### انتخاب کانال

- `stable`: آخرین برچسب غیربتا را checkout می‌کند، سپس build و doctor را اجرا می‌کند.
- `beta`: آخرین برچسب `-beta` را ترجیح می‌دهد، اما وقتی بتا موجود نباشد یا قدیمی‌تر باشد به آخرین برچسب پایدار برمی‌گردد.
- `dev`: `main` را checkout می‌کند، سپس fetch و rebase را اجرا می‌کند.

### گام‌های به‌روزرسانی

<Steps>
  <Step title="بررسی پاک بودن worktree">
    نیاز دارد هیچ تغییر commitنشده‌ای وجود نداشته باشد.
  </Step>
  <Step title="تعویض کانال">
    به کانال انتخاب‌شده (برچسب یا شاخه) جابه‌جا می‌شود.
  </Step>
  <Step title="دریافت upstream">
    فقط برای Dev.
  </Step>
  <Step title="Build پیش‌پرواز (فقط dev)">
    build تایپ‌اسکریپت را در یک worktree موقت اجرا می‌کند. اگر نوک شاخه شکست بخورد، تا 10 commit به عقب می‌رود تا جدیدترین commit قابل build را پیدا کند. برای اینکه lint نیز طی این پیش‌پرواز اجرا شود، `OPENCLAW_UPDATE_PREFLIGHT_LINT=1` را تنظیم کنید؛ lint در حالت سریال محدود اجرا می‌شود، چون میزبان‌های به‌روزرسانی کاربران اغلب از runnerهای CI کوچک‌تر هستند.
  </Step>
  <Step title="Rebase">
    روی commit انتخاب‌شده rebase می‌کند (فقط dev).
  </Step>
  <Step title="نصب وابستگی‌ها">
    از مدیر بستهٔ repo استفاده می‌کند. برای checkoutهای pnpm، به‌روزرسان `pnpm` را هنگام نیاز bootstrap می‌کند (ابتدا از طریق `corepack`، سپس با fallback موقت `npm install pnpm@11`) به‌جای اینکه `npm run build` را داخل یک workspace مربوط به pnpm اجرا کند.
  </Step>
  <Step title="Build کردن Control UI">
    gateway و Control UI را build می‌کند.
  </Step>
  <Step title="اجرای doctor">
    `openclaw doctor` به‌عنوان بررسی نهایی به‌روزرسانی ایمن اجرا می‌شود.
  </Step>
  <Step title="همگام‌سازی پلاگین‌ها">
    پلاگین‌ها را با کانال فعال همگام می‌کند. Dev از پلاگین‌های bundled استفاده می‌کند؛ stable و beta از npm استفاده می‌کنند. نصب‌های پلاگین ردیابی‌شده را به‌روزرسانی می‌کند.
  </Step>
</Steps>

در کانال به‌روزرسانی بتا، نصب‌های پلاگین npm و ClawHub ردیابی‌شده که خط
پیش‌فرض/latest را دنبال می‌کنند ابتدا انتشار `@beta` پلاگین را امتحان می‌کنند.
اگر پلاگین انتشار بتا نداشته باشد، OpenClaw به spec ثبت‌شدهٔ پیش‌فرض/latest
برمی‌گردد و آن را به‌عنوان هشدار گزارش می‌کند. برای پلاگین‌های npm، OpenClaw
همچنین وقتی بستهٔ بتا وجود داشته باشد اما در اعتبارسنجی نصب شکست بخورد برمی‌گردد.
این هشدارهای fallback پلاگین باعث شکست به‌روزرسانی هسته نمی‌شوند. نسخه‌های دقیق
و برچسب‌های صریح بازنویسی نمی‌شوند.

<Warning>
اگر به‌روزرسانی یک پلاگین npm دقیقاً pinشده به artifactی resolve شود که integrity آن با رکورد نصب ذخیره‌شده فرق دارد، `openclaw update` به‌جای نصب آن، به‌روزرسانی artifact آن پلاگین را متوقف می‌کند. فقط پس از بررسی اینکه به artifact جدید اعتماد دارید، پلاگین را دوباره نصب یا صریحاً به‌روزرسانی کنید.
</Warning>

<Note>
شکست‌های همگام‌سازی پلاگین پس از به‌روزرسانی که به یک پلاگین مدیریت‌شده محدود هستند و مسیر همگام‌سازی می‌تواند دورشان بزند (مثلاً registry غیرقابل دسترس npm برای یک پلاگین غیرضروری)، پس از موفقیت به‌روزرسانی هسته به‌عنوان هشدار گزارش می‌شوند. نتیجهٔ JSON، `status: "ok"` سطح بالا را نگه می‌دارد و `postUpdate.plugins.status: "warning"` را همراه با راهنمایی `openclaw doctor --fix` و `openclaw plugins inspect <id> --runtime --json` گزارش می‌کند. استثناهای غیرمنتظرهٔ به‌روزرسان یا همگام‌سازی همچنان نتیجهٔ به‌روزرسانی را شکست می‌دهند. خطای نصب یا به‌روزرسانی پلاگین را رفع کنید، سپس `openclaw doctor --fix` یا `openclaw update` را دوباره اجرا کنید.

پس از گام همگام‌سازی برای هر پلاگین، `openclaw update` پیش از راه‌اندازی مجدد gateway یک گذر اجباری **همگرایی پس از هسته** اجرا می‌کند: payloadهای پلاگین پیکربندی‌شدهٔ گمشده را تعمیر می‌کند، هر رکورد نصب ردیابی‌شدهٔ _فعال_ را روی دیسک اعتبارسنجی می‌کند، و به‌صورت ایستا بررسی می‌کند که `package.json` آن قابل parse باشد (و هر `main` صریحاً اعلام‌شده وجود داشته باشد). شکست‌های این گذر — و snapshot نامعتبر پیکربندی OpenClaw — مقدار `postUpdate.plugins.status: "error"` را برمی‌گردانند و `status` سطح بالا را به `"error"` تغییر می‌دهند، بنابراین `openclaw update` با کد غیرصفر خارج می‌شود و gateway با مجموعهٔ پلاگین راستی‌آزمایی‌نشده راه‌اندازی مجدد _نمی‌شود_. خطا شامل خطوط ساخت‌یافتهٔ `postUpdate.plugins.warnings[].guidance` است که برای پیگیری به `openclaw doctor --fix` و `openclaw plugins inspect <id> --runtime --json` اشاره می‌کنند. ورودی‌های پلاگین غیرفعال و رکوردهایی که به اهداف همگام‌سازی رسمی متصل به منبع مورد اعتماد نیستند اینجا نادیده گرفته می‌شوند، مطابق با سیاست `skipDisabledPlugins` که در بررسی payload گمشده استفاده می‌شود، بنابراین یک رکورد پلاگین غیرفعال قدیمی نمی‌تواند یک به‌روزرسانی در غیر این صورت معتبر را مسدود کند.

وقتی Gateway به‌روزرسانی‌شده شروع به کار می‌کند، بارگذاری پلاگین فقط برای راستی‌آزمایی است: راه‌اندازی، مدیرهای بسته را اجرا نمی‌کند یا درخت‌های وابستگی را تغییر نمی‌دهد. راه‌اندازی‌های مجدد `update.run` مدیر بسته پس از جابه‌جایی درخت بسته، تعویق معمول زمان بیکاری و دورهٔ خنک‌سازی راه‌اندازی مجدد را دور می‌زنند، بنابراین فرایند قدیمی نمی‌تواند به lazy-loading قطعه‌های حذف‌شده ادامه دهد.

اگر bootstrap مربوط به pnpm همچنان شکست بخورد، به‌روزرسان به‌جای تلاش برای اجرای `npm run build` داخل checkout، زودتر با یک خطای مخصوص مدیر بسته متوقف می‌شود.
</Note>

## میان‌بر `--update`

`openclaw --update` به `openclaw update` بازنویسی می‌شود (برای shellها و اسکریپت‌های launcher مفید است).

## مرتبط

- `openclaw doctor` (در checkoutهای git پیشنهاد می‌کند ابتدا update را اجرا کند)
- [کانال‌های توسعه](/fa/install/development-channels)
- [به‌روزرسانی](/fa/install/updating)
- [مرجع CLI](/fa/cli)