openclaw update

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

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

کاربرد

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw 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

گزینه‌ها

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

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

update status

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

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

گزینه‌ها:

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

update repair

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

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

گزینه‌ها:

• --channel <stable|beta|dev>: کانال به‌روزرسانی را پیش از تعمیر پایدار کنید و همگرایی Plugin را در برابر همان کانال اجرا کنید.
• --json: JSON نهایی‌سازی خواندنی برای ماشین را چاپ کنید.
• --timeout <seconds>: مهلت زمانی برای گام‌های تعمیر (پیش‌فرض 1800).
• --yes: پرسش‌های تأیید را رد کنید.
• --acknowledge-clawhub-risk: پس از بازبینی هشدارهای اعتماد ClawHub جامعه، اجازه دهید همگرایی Plugin هنگام تعمیر بدون یک پرسش تعاملی ادامه پیدا کند. بسته‌های رسمی ClawHub و منابع Plugin همراه OpenClaw این پرسش اعتماد به انتشار را دور می‌زنند.
• --no-restart: برای هم‌ارزی با دستور update پذیرفته می‌شود؛ repair هرگز Gateway را دوباره راه‌اندازی نمی‌کند.

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

update wizard

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

گزینه‌ها:

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

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

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

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

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

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

وقتی یک سرویس Gateway مدیریت‌شده‌ی محلی نصب شده و راه‌اندازی دوباره فعال باشد، به‌روزرسانی‌های مدیر بسته و checkout مربوط به git پیش از جایگزین کردن درخت بسته یا تغییر checkout/خروجی build، سرویس در حال اجرا را متوقف می‌کنند. سپس به‌روزرسان فراداده‌ی سرویس را از نصب به‌روزشده تازه می‌کند، سرویس را دوباره راه‌اندازی می‌کند، و پیش از گزارش دادن Gateway: restarted and verified. Gateway دوباره‌راه‌اندازی‌شده را بررسی می‌کند. به‌روزرسانی‌های مدیر بسته علاوه بر این بررسی می‌کنند Gateway دوباره‌راه‌اندازی‌شده نسخه‌ی بسته‌ی مورد انتظار را گزارش می‌دهد؛ به‌روزرسانی‌های checkout مربوط به git سلامت gateway و آمادگی سرویس را پس از بازسازی بررسی می‌کنند. در macOS، بررسی پس از به‌روزرسانی همچنین تأیید می‌کند LaunchAgent برای profile فعال بارگذاری/در حال اجرا است و پورت loopback پیکربندی‌شده سالم است. اگر plist نصب شده باشد اما launchd آن را تحت نظارت نداشته باشد، OpenClaw به‌طور خودکار LaunchAgent را دوباره bootstrap می‌کند، سپس بررسی‌های آمادگی سلامت/نسخه/کانال را دوباره اجرا می‌کند. یک bootstrap تازه کار RunAtLoad را مستقیماً بارگذاری می‌کند، بنابراین بازیابی به‌روزرسانی بلافاصله Gateway تازه ایجادشده را kickstart -k نمی‌کند. اگر Gateway همچنان سالم نشود، دستور با کد غیرصفر خارج می‌شود و مسیر لاگ راه‌اندازی دوباره به‌همراه دستورالعمل‌های صریح راه‌اندازی دوباره، نصب دوباره، و rollback بسته را چاپ می‌کند. اگر راه‌اندازی دوباره نتواند اجرا شود، دستور Gateway: restart skipped (...) یا Gateway: restart failed: ... را با راهنمای دستی openclaw gateway restart چاپ می‌کند. با --no-restart، جایگزینی بسته یا بازسازی git همچنان اجرا می‌شود اما سرویس مدیریت‌شده متوقف یا دوباره راه‌اندازی نمی‌شود، بنابراین Gateway در حال اجرا ممکن است تا وقتی آن را دستی دوباره راه‌اندازی کنید، کد قدیمی را نگه دارد.

شکل پاسخ کنترل‌پلین

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

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

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

جریان checkout مربوط به git

انتخاب کانال

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

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

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

shorthand مربوط به --update

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

مرتبط

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