openclaw update

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

اگر از طریق npm/pnpm/bun نصب کرده‌اید (نصب سراسری، بدون فرادادهٔ git)، به‌روزرسانی‌ها از جریان مدیر بسته که در به‌روزرسانی شرح داده شده است، انجام می‌شوند.

روش استفاده

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw update --channel extended-stableopenclaw update --channel betaopenclaw update --channel devopenclaw update --tag betaopenclaw update --tag mainopenclaw update --dry-runopenclaw update --no-restartopenclaw update --yesopenclaw update --acknowledge-clawhub-riskopenclaw update --jsonopenclaw --update

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

گزینه‌ها

پرچم --verbose وجود ندارد. برای پیش‌نمایش اقدامات برنامه‌ریزی‌شده از --dry-run، برای نتایج خوانا برای ماشین از --json، و فقط برای کانال/دسترس‌پذیری از openclaw update status --json استفاده کنید. میزان جزئیات کنسول Gateway ‏(--verbose) و سطح گزارش فایل (logging.level: "debug"/"trace") تنظیمات مستقلی هستند؛ گزارش‌گیری Gateway را ببینید.

update status

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

openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10

برای نصب‌های بسته‌ای پایدارِ بلندمدت، وضعیت همان گزینشگر عمومی و تأیید بستهٔ دقیق را مانند به‌روزرسانی پیش‌زمینه انجام می‌دهد. اگر نسخهٔ نصب‌شده جدیدتر باشد، می‌تواند ahead of extended-stable را گزارش کند. خطاهای JSON شامل registry.reason ‏(selector_missing، selector_query_failed، exact_package_mismatch یا unsupported_git_channel) هستند.

update repair

پس از اینکه بستهٔ هسته از قبل تغییر کرده اما کارهای تعمیر بعدی به‌طور کامل و صحیح پایان نیافته‌اند، نهایی‌سازی به‌روزرسانی را دوباره اجرا می‌کند. این مسیر بازیابی پشتیبانی‌شده هنگامی است که openclaw update بستهٔ هستهٔ جدید را نصب کرده، اما همگام‌سازی Plugin پس از هسته، فرادادهٔ Plugin مدیریت‌شدهٔ npm، نوسازی رجیستری یا تعمیر Doctor همگرا نشده است.

openclaw update repairopenclaw update repair --channel betaopenclaw update repair --acknowledge-clawhub-riskopenclaw update repair --json

update repair، ‏openclaw doctor --fix را اجرا می‌کند، پیکربندی تعمیرشده و رکوردهای نصب را دوباره بارگذاری می‌کند، Pluginهای ردیابی‌شده را برای کانال فعال به‌روزرسانی همگام می‌کند، نصب‌های Plugin مدیریت‌شدهٔ npm را به‌روزرسانی می‌کند، محتوای Plugin پیکربندی‌شدهٔ مفقود را تعمیر می‌کند، رجیستری Plugin را نوسازی می‌کند و فرادادهٔ رکورد نصب همگراشده را می‌نویسد. این کار بستهٔ هستهٔ جدیدی نصب نمی‌کند و Gateway را راه‌اندازی مجدد نمی‌کند.

update wizard

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

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

جابه‌جایی صریح کانال‌ها (--channel ...) روش نصب را نیز هم‌تراز نگه می‌دارد:

• dev -> وجود یک پرداخت git را تضمین می‌کند (پیش‌فرض ~/openclaw، یا وقتی OPENCLAW_HOME تنظیم شده است، $OPENCLAW_HOME/openclaw؛ با OPENCLAW_GIT_DIR لغو کنید)، آن را به‌روزرسانی می‌کند و CLI سراسری را از آن پرداخت نصب می‌کند.
• stable -> با استفاده از latest از npm نصب می‌کند.
• extended-stable -> گزینشگر عمومی npm با نام extended-stable را تفکیک می‌کند، بستهٔ دقیق انتخاب‌شده را تأیید می‌کند و همان نسخهٔ دقیق را نصب می‌کند. این فرایند به گزینشگر دیگری بازنمی‌گردد و برای پرداخت‌های Git رد می‌شود.
• beta -> برچسب توزیع npm با نام beta را ترجیح می‌دهد و اگر بتا موجود نباشد یا از انتشار پایدار فعلی قدیمی‌تر باشد، به latest بازمی‌گردد.

تحویل راه‌اندازی مجدد

به‌روزرسان خودکار هستهٔ Gateway (هنگامی که از طریق پیکربندی فعال باشد)، مسیر به‌روزرسانی CLI را خارج از کنترل‌کنندهٔ درخواست زندهٔ Gateway اجرا می‌کند. به‌روزرسانی‌های مدیر بستهٔ صفحهٔ کنترل update.run و به‌روزرسانی‌های پرداخت git تحت نظارت، به‌جای جایگزینی درخت بسته یا بازسازی dist/ درون فرایند زندهٔ Gateway، از همان تحویل سرویس مدیریت‌شده استفاده می‌کنند: Gateway یک کمک‌کنندهٔ جداشده را آغاز می‌کند و خارج می‌شود، سپس آن کمک‌کننده openclaw update --yes --json را خارج از درخت فرایند Gateway اجرا می‌کند. اگر تحویل در دسترس نباشد، update.run پاسخی ساختاریافته همراه با فرمان پوستهٔ امنی که باید به‌صورت دستی اجرا شود، بازمی‌گرداند.

انتخاب‌های extended-stable ذخیره‌شده، هنگامی که update.checkOnStart فعال باشد، هنگام راه‌اندازی و هر 24 ساعت راهنمایی‌های فقط‌خواندنی به‌روزرسانی دریافت می‌کنند. این بررسی‌ها هرگز به‌روزرسانی را اعمال نمی‌کنند، handoff را آغاز نمی‌کنند، Gateway را راه‌اندازی مجدد نمی‌کنند، از تأخیر/لرزش پایدار استفاده نمی‌کنند یا از آهنگ نظرسنجی بتا بهره نمی‌برند. به‌روزرسانی‌های صریح پیش‌زمینه، به‌روزرسانی‌های ساده پیش‌زمینه با update.channel: "extended-stable" ذخیره‌شده، وضعیت درخواستی و handoff مدیریت‌شده Gateway مربوط به آن‌ها همچنان پشتیبانی می‌شوند.

هنگامی که یک سرویس Gateway مدیریت‌شده محلی نصب شده و راه‌اندازی مجدد فعال باشد، به‌روزرسانی‌های مدیر بسته و checkout گیت، پیش از جایگزینی درخت بسته یا تغییر checkout/خروجی build، سرویس در حال اجرا را متوقف می‌کنند. سپس به‌روزرسان فراداده سرویس را تازه‌سازی می‌کند، سرویس را مجدداً راه‌اندازی می‌کند و پیش از گزارش Gateway: restarted and verified.، Gateway راه‌اندازی‌مجددشده را تأیید می‌کند. به‌روزرسانی‌های مدیر بسته همچنین تأیید می‌کنند که Gateway راه‌اندازی‌مجددشده نسخه مورد انتظار بسته را گزارش می‌دهد؛ به‌روزرسانی‌های checkout گیت، پس از build مجدد، سلامت Gateway و آمادگی سرویس را تأیید می‌کنند.

به‌روزرسانی‌های مدیر بسته معمولاً همچنان از باینری Node ثبت‌شده در سرویس مدیریت‌شده استفاده می‌کنند. اگر آن Node نتواند انتشار مقصد را اجرا کند، اما Node فعلی CLI بتواند و ثابت شده باشد که سرویس متعلق به بسته در حال به‌روزرسانی است، یک به‌روزرسانی با راه‌اندازی مجدد فعال، برای نهایی‌سازی از Node فعلی استفاده می‌کند و فراداده سرویس را برای آن runtime بازنویسی می‌کند. --no-restart نمی‌تواند فراداده سرویس را تعمیر کند، بنابراین همان ناسازگاری runtime پیش از تغییر بسته، فرایند را متوقف می‌کند.

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

اگر راه‌اندازی مجدد قابل اجرا نباشد، فرمان Gateway: restart skipped (...) یا Gateway: restart failed: ... را همراه با راهنمای دستی openclaw gateway restart نمایش می‌دهد. با --no-restart، جایگزینی بسته یا build مجدد گیت همچنان اجرا می‌شود، اما سرویس مدیریت‌شده متوقف یا مجدداً راه‌اندازی نمی‌شود؛ بنابراین Gateway در حال اجرا تا زمانی که آن را به‌صورت دستی راه‌اندازی مجدد کنید، همچنان از کد قدیمی استفاده می‌کند.

ساختار پاسخ صفحه کنترل

هنگامی که update.run از طریق صفحه کنترل Gateway روی یک نصب مدیر بسته یا checkout گیت تحت نظارت اجرا می‌شود، handler آغاز handoff را جدا از به‌روزرسانی CLI که پس از خروج Gateway ادامه می‌یابد گزارش می‌کند:

• ok: true، result.status: "skipped"، result.reason: "managed-service-handoff-started" و handoff.status: "started": Gateway، handoff سرویس مدیریت‌شده را ایجاد کرد و راه‌اندازی مجدد خود را زمان‌بندی کرد تا helper جداشده بتواند openclaw update --yes --json را خارج از فرایند سرویس زنده اجرا کند.
• ok: false، result.reason: "managed-service-handoff-unavailable" و handoff.status: "unavailable": OpenClaw نتوانست مرز سرویس تحت نظارت و هویت پایدار سرویس را برای یک handoff ایمن پیدا کند (برای نمونه، handoff مربوط به systemd به هویت واحد OPENCLAW_SYSTEMD_UNIT نیاز دارد، نه صرفاً نشانگرهای محیطی فرایند systemd). پاسخ شامل handoff.command، یعنی فرمان shell برای اجرا از خارج Gateway است.
• ok: false، result.reason: "managed-service-handoff-failed": Gateway تلاش کرد handoff را ایجاد کند، اما نتوانست helper جداشده را اجرا کند.

payload مربوط به sentinel پیش از خروج Gateway نوشته می‌شود و handoff CLI، همان sentinel راه‌اندازی مجدد را پس از تکمیل بررسی‌های سلامت راه‌اندازی مجدد سرویس مدیریت‌شده به‌روزرسانی می‌کند. در طول handoff، sentinel می‌تواند stats.reason: "restart-health-pending" را بدون ادامه موفقیت در خود داشته باشد؛ Gateway راه‌اندازی‌مجددشده آن را نظرسنجی می‌کند و تنها پس از آن‌که CLI سلامت سرویس را تأیید و sentinel را با نتیجه نهایی ok بازنویسی کرد، ادامه را اجرا می‌کند. openclaw status و openclaw status --all تا زمانی که آن sentinel در انتظار یا ناموفق باشد، یک ردیف Update restart نمایش می‌دهند و update.status تازه‌سازی می‌کند و آخرین sentinel را برمی‌گرداند.

جریان checkout گیت

انتخاب کانال

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

مراحل به‌روزرسانی

جزئیات همگام‌سازی Plugin

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

پس از موفقیت یک به‌روزرسانی extended-stable هسته، یکپارچگی و همگرایی Plugin پس از هسته، Pluginهای رسمی واجد شرایط npm را در نسخه دقیق هسته نصب‌شده هدف قرار می‌دهد. برای قصد پیش‌فرض/latest، ‏OpenClaw از @extended-stable مربوط به Plugin پرس‌وجو نمی‌کند و به latest در npm fallback نمی‌کند؛ نسخه بسته را از هسته نصب‌شده استخراج می‌کند. pinهای صریح نسخه، تگ‌های صریح غیر-latest، بسته‌های شخص ثالث و منابع غیر-npm قصد موجود خود را حفظ می‌کنند.

برای نصب‌های مدیر بسته، openclaw update پیش از فراخوانی مدیر بسته، نسخه بسته مقصد را resolve می‌کند. نصب‌های سراسری npm از نصب مرحله‌ای استفاده می‌کنند: OpenClaw بسته جدید را در یک prefix موقت npm نصب می‌کند، به بسته کاندید اجازه می‌دهد هنگام preinstall نسخه Node میزبان را اعتبارسنجی کند و موجودی بسته‌بندی‌شده dist را در آنجا تأیید می‌کند. یک محافظ تکمیل بسته‌بندی‌شده تا زمان موفقیت preinstall خارج از آن موجودی باقی می‌ماند؛ بنابراین مدیرهای بسته‌ای که اسکریپت‌های چرخه عمر را نادیده می‌گیرند نیز پیش از فعال‌سازی متوقف می‌شوند. در npm 12 و نسخه‌های جدیدتر، به‌روزرسان تنها چرخه عمر OpenClaw کاندید را تأیید می‌کند؛ اسکریپت‌های وابستگی‌های گذرا همچنان مسدود می‌مانند. سپس OpenClaw درخت بسته تمیز را به prefix سراسری واقعی منتقل می‌کند. اگر تأیید ناموفق باشد، doctor پس از به‌روزرسانی، همگام‌سازی Plugin و عملیات راه‌اندازی مجدد از درخت مشکوک اجرا نمی‌شوند. حتی هنگامی که نسخه نصب‌شده از قبل با مقصد مطابقت دارد، فرمان نصب سراسری بسته را تازه‌سازی می‌کند و سپس همگام‌سازی Plugin، تازه‌سازی تکمیل فرمان هسته و عملیات راه‌اندازی مجدد را اجرا می‌کند. این کار sidecarهای بسته‌بندی‌شده و رکوردهای Plugin متعلق به کانال را با build نصب‌شده OpenClaw هم‌راستا نگه می‌دارد، در حالی که بازسازی‌های کامل تکمیل فرمان Plugin را به اجرای صریح openclaw completion --write-state واگذار می‌کند.

مرتبط

• openclaw doctor (پیشنهاد می‌کند ابتدا به‌روزرسانی را روی checkoutهای گیت اجرا کند)
• کانال‌های توسعه
• به‌روزرسانی
• مرجع CLI