CLI commands
بهروزرسانی
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 --updateopenclaw --update به openclaw update بازنویسی میشود (برای پوستهها و
اسکریپتهای راهانداز مفید است).
گزینهها
| پرچم | توضیحات |
|---|---|
--no-restart |
پس از بهروزرسانی موفق، از راهاندازی مجدد سرویس Gateway صرفنظر میکند. بهروزرسانیهای مدیر بسته که سرویس را راهاندازی مجدد میکنند، پیش از موفقشدن فرمان بررسی میکنند که سرویسِ راهاندازیشدهٔ مجدد، نسخهٔ مورد انتظار را گزارش دهد. |
--channel <stable|extended-stable|beta|dev> |
کانال بهروزرسانی را تنظیم میکند و پس از موفقیت بهروزرسانی هسته، آن را ماندگار میسازد. پایدارِ توسعهیافته فقط برای بستهها است. |
--tag <dist-tag|version|spec> |
هدف بسته را فقط برای این بهروزرسانی بازنویسی میکند. نمیتوان آن را با کانال مؤثر extended-stable ترکیب کرد، زیرا هدف دقیق و تأییدشدهٔ آن الزامی است. برای سایر نصبهای بستهای، main به github:openclaw/openclaw#main نگاشت میشود؛ مشخصات منبع GitHub/git پیش از نصب سراسری مرحلهبندیشده با npm، در یک tarball موقت بستهبندی میشوند. |
--dry-run |
بدون نوشتن پیکربندی، نصب، همگامسازی Pluginها یا راهاندازی مجدد، اقدامات برنامهریزیشده (جریان کانال/برچسب/هدف/راهاندازی مجدد) را پیشنمایش میکند. |
--json |
JSON قابلخواندن برای ماشینِ UpdateRunResult را چاپ میکند. هنگامی که یک Plugin مدیریتشده به تعمیر نیاز دارد، شامل postUpdate.plugins.warnings، جزئیات عقبگرد Plugin کانال بتا، و هنگامی که ناهمخوانی مصنوع npm مربوط به Plugin طی همگامسازی پس از بهروزرسانی تشخیص داده شود، شامل postUpdate.plugins.integrityDrifts است. |
--timeout <seconds> |
مهلت زمانی هر مرحله. مقدار پیشفرض 1800 است. |
--yes |
درخواستهای تأیید را نادیده میگیرد (برای نمونه، تأیید تنزل نسخه). |
--acknowledge-clawhub-risk |
اجازه میدهد همگامسازی Plugin پس از بهروزرسانی، بدون درخواست تعاملی از هشدارهای اعتماد جامعهٔ ClawHub عبور کند. بدون آن، وقتی OpenClaw نتواند درخواست تأیید نمایش دهد، انتشارهای پرخطر جامعه نادیده گرفته میشوند و بدون تغییر باقی میمانند. بستههای رسمی ClawHub و منابع Plugin همراه از این درخواست عبور میکنند. |
هیچ پرچم --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| پرچم | پیشفرض | توضیحات |
|---|---|---|
--json |
false |
JSON وضعیت قابلخواندن برای ماشین را چاپ میکند. |
--timeout <seconds> |
3 |
مهلت زمانی بررسیها. |
برای نصبهای بستهای پایدارِ توسعهیافته، وضعیت همان انتخابگر عمومی
و تأیید دقیق بسته را مانند بهروزرسانی پیشزمینه انجام میدهد. اگر نسخهٔ نصبشده جدیدتر باشد،
میتواند 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| پرچم | توضیحات |
|---|---|
--channel <stable|extended-stable|beta|dev> |
کانال بهروزرسانی هسته را پیش از تعمیر ماندگار میکند. برای پایدارِ توسعهیافته، Pluginهای رسمی و واجد شرایط npm که از هدف صریح/پیشفرض یا مقصود latest پیروی میکنند، نسخهٔ دقیق هستهٔ نصبشده را هدف قرار میدهند. تعمیر پایدارِ توسعهیافته در وارسیهای Git بدون تغییر پیکربندی رد میشود. |
--json |
JSON نهاییسازی قابلخواندن برای ماشین را چاپ میکند. |
--timeout <seconds> |
مهلت زمانی مراحل تعمیر. مقدار پیشفرض 1800 است. |
--yes |
درخواستهای تأیید را نادیده میگیرد. |
--acknowledge-clawhub-risk |
رفتاری همانند openclaw update دارد. |
--no-restart |
برای همسانی پذیرفته میشود؛ تعمیر هرگز Gateway را راهاندازی مجدد نمیکند. |
update repair، openclaw doctor --fix را اجرا میکند، پیکربندی تعمیرشده و
رکوردهای نصب را دوباره بارگذاری میکند، Pluginهای ردیابیشده را برای کانال فعال بهروزرسانی همگام میکند،
نصبهای Plugin مدیریتشدهٔ npm را بهروزرسانی میکند، بارهای محتوایی مفقود Pluginهای پیکربندیشده را تعمیر میکند،
رجیستری Plugin را تازهسازی میکند و فرادادهٔ همگرای رکورد نصب را مینویسد.
این فرمان بستهٔ جدید هسته را نصب نمیکند و Gateway را راهاندازی مجدد نمیکند.
update wizard
جریان تعاملی برای انتخاب کانال بهروزرسانی و تأیید راهاندازی مجدد Gateway
پس از آن (پیشفرض، راهاندازی مجدد است). انتخاب dev بدون وارسی git،
ایجاد یک وارسی را پیشنهاد میدهد.
| پرچم | پیشفرض | توضیحات |
|---|---|---|
--timeout <seconds> |
1800 |
مهلت زمانی هر مرحلهٔ بهروزرسانی. |
کاری که انجام میدهد
جابهجایی صریح کانالها (--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 را بازراهاندازی نمیکنند، از تأخیر/jitter شاخه stable استفاده نمیکنند یا از
تناوب نظرسنجی beta بهره نمیبرند. بهروزرسانیهای صریح پیشزمینه، بهروزرسانیهای ساده پیشزمینه با
update.channel: "extended-stable" ذخیرهشده، وضعیت درخواستی و handoff مدیریتشده
Gateway آنها همچنان پشتیبانی میشوند.
وقتی یک سرویس Gateway مدیریتشده محلی نصب شده و بازراهاندازی فعال باشد،
بهروزرسانیهای مدیر بسته و git checkout پیش از جایگزینی درخت بسته یا
تغییر checkout/خروجی ساخت، سرویس در حال اجرا را متوقف میکنند. سپس بهروزرسان
فراداده سرویس را تازهسازی میکند، سرویس را بازراهاندازی میکند و پیش از گزارش
Gateway: restarted and verified.، Gateway بازراهاندازیشده را تأیید میکند.
بهروزرسانیهای مدیر بسته علاوه بر این تأیید میکنند که Gateway بازراهاندازیشده
نسخه مورد انتظار بسته را گزارش میدهد؛ بهروزرسانیهای git checkout نیز پس از
بازسازی، سلامت Gateway و آمادگی سرویس را تأیید میکنند.
بهروزرسانیهای مدیر بسته معمولاً همچنان از باینری Node ثبتشده در
سرویس مدیریتشده استفاده میکنند. اگر آن Node نتواند نسخه انتشار هدف را اجرا کند، اما
Node فعلی CLI بتواند و تعلق سرویس به بستهای که بهروزرسانی میشود اثبات شده باشد،
یک بهروزرسانی با بازراهاندازی فعال، برای نهاییسازی از Node فعلی استفاده میکند و
فراداده سرویس را برای آن محیط اجرا بازنویسی میکند. --no-restart نمیتواند فراداده
سرویس را ترمیم کند، بنابراین همان ناهماهنگی محیط اجرا پیش از تغییر بسته عملیات را متوقف میکند.
در macOS، بررسی پس از بهروزرسانی همچنین تأیید میکند که LaunchAgent برای
پروفایل فعال بارگذاری شده/در حال اجرا است و پورت loopback پیکربندیشده
سالم است. اگر plist نصب شده باشد اما launchd بر آن نظارت نکند، OpenClaw
بهطور خودکار LaunchAgent را دوباره bootstrap میکند و بررسیهای سلامت/نسخه/
آمادگی کانال را مجدداً اجرا میکند (یک bootstrap تازه، کار RunAtLoad را مستقیماً بارگذاری میکند،
بنابراین بازیابی بلافاصله Gateway تازه ایجادشده را kickstart -k نمیکند). اگر
Gateway همچنان سالم نشود، فرمان با کد غیرصفر خارج میشود و
مسیر گزارش بازراهاندازی را همراه با دستورالعملهای بازراهاندازی، نصب مجدد و بازگردانی
بسته چاپ میکند.
اگر بازراهاندازی قابل اجرا نباشد، فرمان Gateway: restart skipped (...) یا
Gateway: restart failed: ... را همراه با راهنمای دستی openclaw gateway restart چاپ میکند.
با --no-restart، جایگزینی بسته یا بازسازی git همچنان اجرا میشود، اما
سرویس مدیریتشده متوقف یا بازراهاندازی نمیشود؛ بنابراین Gateway در حال اجرا تا زمانی که
آن را بهصورت دستی بازراهاندازی کنید، همچنان از کد قدیمی استفاده میکند.
ساختار پاسخ صفحه کنترل
وقتی update.run از طریق صفحه کنترل Gateway روی یک نصب
مدیر بسته یا git checkout تحت نظارت اجرا شود، کنترلکننده آغاز handoff را
جدا از بهروزرسانی CLI که پس از خروج Gateway ادامه مییابد گزارش میکند:
ok: true،result.status: "skipped"،result.reason: "managed-service-handoff-started"وhandoff.status: "started": Gateway، handoff سرویس مدیریتشده را ایجاد و بازراهاندازی خود را زمانبندی کرد تا کمککننده جداشده بتواند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 را ایجاد کند، اما نتوانست کمککننده جداشده را اجرا کند.
بار داده sentinel پیش از خروج Gateway نوشته میشود و handoff
CLI، همان نشانگر بازراهاندازی را پس از تکمیل بررسیهای سلامت بازراهاندازی
سرویس مدیریتشده بهروزرسانی میکند. در طول handoff، نشانگر میتواند
stats.reason: "restart-health-pending" را بدون ادامه موفقیت در خود داشته باشد؛
Gateway بازراهاندازیشده آن را نظرسنجی میکند و فقط پس از آنکه CLI
سلامت سرویس را تأیید و نشانگر را با نتیجه نهایی ok بازنویسی کرد،
ادامه را فعال میکند.
openclaw status و openclaw status --all تا زمانی که آن نشانگر در انتظار یا ناموفق باشد،
یک ردیف Update restart نشان میدهند و update.status آن را تازهسازی
کرده و جدیدترین نشانگر را بازمیگرداند.
جریان git checkout
انتخاب کانال
stable: جدیدترین برچسب غیر beta را checkout کنید، سپس ساخت و doctor را اجرا کنید.beta: جدیدترین برچسب-betaرا ترجیح میدهد و اگر beta وجود نداشته باشد یا قدیمیتر باشد، به جدیدترین برچسب stable برمیگردد.dev:mainرا checkout میکند، سپس fetch و rebase را اجرا میکند.extended-stable: برای Git checkout پشتیبانی نمیشود؛ هیچ تغییری در checkout انجام نمیشود.
مراحل بهروزرسانی
تأیید پاکبودن درخت کاری
مستلزم نبود تغییرات commitنشده است.
تغییر کانال
به کانال انتخابشده (برچسب یا شاخه) تغییر میکند.
دریافت از بالادست
فقط برای dev.
ساخت پیشبررسی (فقط dev)
ساخت TypeScript را در یک درخت کاری موقت اجرا میکند. اگر نوک شاخه ناموفق باشد، حداکثر 10 commit به عقب میرود تا جدیدترین commit قابل ساخت را پیدا کند. برای اجرای lint در این پیشبررسی نیز OPENCLAW_UPDATE_PREFLIGHT_LINT=1 را تنظیم کنید؛ lint در حالت سری محدودشده اجرا میشود، زیرا میزبانهای بهروزرسانی کاربران اغلب از اجراکنندههای CI کوچکترند.
Rebase
روی commit انتخابشده rebase میکند (فقط dev).
نصب وابستگیها
از مدیر بسته مخزن استفاده میکند. برای checkoutهای pnpm، بهروزرسان در صورت نیاز pnpm را bootstrap میکند (ابتدا از طریق corepack و سپس با fallback موقت npm install pnpm@11)، بهجای آنکه npm run build را داخل یک فضای کاری pnpm اجرا کند. اگر bootstrap کردن pnpm همچنان ناموفق باشد، بهروزرسان با خطایی مختص مدیر بسته زودتر متوقف میشود، بهجای آنکه npm run build را در checkout امتحان کند.
ساخت رابط کنترل
Gateway و رابط کنترل را میسازد.
اجرای doctor
openclaw doctor بهعنوان آخرین بررسی بهروزرسانی ایمن اجرا میشود.
همگامسازی Pluginها
Pluginها را با کانال فعال همگام میکند. dev از Pluginهای همراه استفاده میکند؛ stable و beta از npm استفاده میکنند. نصبهای Plugin ردیابیشده را بهروزرسانی میکند.
جزئیات همگامسازی Plugin
در کانال beta، نصبهای ردیابیشده Plugin از npm و ClawHub که خط
پیشفرض/latest را دنبال میکنند، ابتدا یک انتشار @beta از Plugin را امتحان میکنند. اگر Plugin
انتشار beta نداشته باشد، OpenClaw به مشخصات پیشفرض/latest ثبتشده
برمیگردد و هشداری گزارش میکند. برای Pluginهای npm، OpenClaw همچنین زمانی fallback
میکند که بسته beta موجود باشد اما اعتبارسنجی نصب آن ناموفق شود. این هشدارهای fallback
باعث شکست بهروزرسانی هسته نمیشوند. نسخههای دقیق و برچسبهای صریح هرگز بازنویسی نمیشوند.
پس از موفقیت یک بهروزرسانی هسته extended-stable، یکپارچگی و
همگرایی Plugin پس از هسته، Pluginهای رسمی واجد شرایط npm را دقیقاً در نسخه
نصبشده هسته هدف میگیرند. برای مقصود پیشفرض/latest، OpenClaw
@extended-stable مربوط به Plugin را استعلام نمیکند و به latest در npm fallback نمیکند؛
نسخه بسته را از هسته نصبشده استخراج میکند. سنجاقهای صریح نسخه، برچسبهای صریح غیر latest،
بستههای شخص ثالث و منابع غیر npm مقصود موجود خود را حفظ میکنند.
برای نصبهای مدیر بسته، openclaw update پیش از فراخوانی مدیر بسته،
نسخه بسته هدف را تعیین میکند. نصبهای global در npm از نصب مرحلهای استفاده میکنند:
OpenClaw بسته جدید را در یک prefix موقت npm نصب میکند،
به بسته نامزد اجازه میدهد طی preinstall نسخه Node میزبان را اعتبارسنجی کند
و فهرست dist بستهبندیشده را در آنجا تأیید میکند. یک محافظ تکمیل بستهبندیشده
تا زمان موفقیت preinstall خارج از آن فهرست باقی میماند؛ بنابراین مدیرهای بستهای
که اسکریپتهای چرخه عمر را نادیده میگیرند نیز پیش از فعالسازی متوقف میشوند. در npm 12 و نسخههای جدیدتر،
بهروزرسان فقط چرخه عمر OpenClaw نامزد را تأیید میکند؛ اسکریپتهای
وابستگیهای انتقالی مسدود باقی میمانند. سپس OpenClaw درخت پاک بسته را
به prefix واقعی global منتقل میکند. اگر تأیید ناموفق باشد، doctor پس از بهروزرسانی،
همگامسازی Plugin و عملیات بازراهاندازی از درخت مشکوک اجرا نمیشوند. حتی وقتی
نسخه نصبشده از قبل با هدف مطابقت داشته باشد، فرمان نصب
بسته global را تازهسازی میکند و سپس همگامسازی Plugin، تازهسازی تکمیل
فرمان هسته و عملیات بازراهاندازی را اجرا میکند. این کار sidecarهای بستهبندیشده و رکوردهای
Plugin متعلق به کانال را با ساخت نصبشده OpenClaw همراستا نگه میدارد، درحالیکه بازسازیهای کامل
تکمیل فرمان Plugin را به اجرای صریح
openclaw completion --write-state واگذار میکند.
مرتبط
openclaw doctor(در git checkout پیشنهاد میدهد ابتدا بهروزرسانی اجرا شود)- کانالهای توسعه
- بهروزرسانی
- مرجع CLI
