Skip to main content

​
openclaw update

حدّث OpenClaw وبدّل بين قنوات stable/extended-stable/beta/dev. إذا ثبّتَّ عبر npm/pnpm/bun (تثبيت عام، دون بيانات git الوصفية)، فتُجرى التحديثات عبر مسار مدير الحزم الموضّح في التحديث.

​
الاستخدام

تُعاد كتابة openclaw --update إلى openclaw update (وهو مفيد للصدفات وبرامج تشغيل البدء).

​
الخيارات

لا توجد علامة --verbose. استخدم --dry-run لمعاينة الإجراءات المخططة، و--json للنتائج القابلة للقراءة آليًا، وopenclaw update status --json للقناة/التوفر فقط. إسهاب وحدة تحكم Gateway ‏(--verbose) ومستوى سجل الملف (logging.level: "debug"/"trace") إعدادان مستقلان؛ راجع تسجيل Gateway.
في وضع Nix ‏(OPENCLAW_NIX_MODE=1)، تُعطّل عمليات openclaw update التي تُجري تغييرات. حدّث مصدر Nix أو مُدخل flake لهذا التثبيت بدلًا من ذلك؛ وبالنسبة إلى nix-openclaw، استخدم البدء السريع الذي يبدأ بالوكيل. يظل openclaw update status وopenclaw update --dry-run للقراءة فقط.
يتطلب الرجوع إلى إصدار أقدم تأكيدًا لأن الإصدارات القديمة قد تُعطّل الإعدادات. إذا كان التثبيت قد رحّل الجلسات بالفعل إلى SQLite، فاستعد عناصر نصوص المحادثات القديمة المؤرشفة قبل بدء إصدار أقدم يعتمد على الملفات. راجع Doctor: الرجوع إلى إصدار أقدم بعد ترحيل الجلسات إلى SQLite.

​
update status

اعرض قناة التحديث النشطة ووسم/فرع/SHA ‏git (لنسخ المصدر المستنسخة فقط)، ومدى توفر تحديث.
بالنسبة إلى تثبيتات حزم extended-stable، تنفّذ الحالة محدد الاختيار العام نفسه والتحقق من الحزمة الدقيقة نفسه المستخدمين في التحديث الأمامي. ويمكنها الإبلاغ عن 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 لم تصل إلى حالة متسقة.
يشغّل update repair الأمر openclaw doctor --fix، ويعيد تحميل الإعدادات وسجلات التثبيت التي أُصلحت، ويزامن Plugins المتتبعة لقناة التحديث النشطة، ويحدّث تثبيتات Plugins المُدارة في npm، ويصلح حمولات Plugins المكوّنة والمفقودة، ويحدّث سجل Plugins، ويكتب بيانات وصفية متسقة لسجلات التثبيت. ولا يثبّت حزمة أساسية جديدة ولا يعيد تشغيل Gateway.

​
update wizard

مسار تفاعلي لاختيار قناة تحديث وتأكيد ما إذا كان يجب إعادة تشغيل Gateway بعد ذلك (الافتراضي هو إعادة التشغيل). يؤدي اختيار dev من دون نسخة git مستنسخة إلى عرض إنشاء واحدة.

​
ما يفعله

يؤدي التبديل الصريح بين القنوات (--channel ...) أيضًا إلى إبقاء طريقة التثبيت متوافقة:
  • dev -> يضمن وجود نسخة git مستنسخة (القيمة الافتراضية ~/openclaw، أو $OPENCLAW_HOME/openclaw عند تعيين OPENCLAW_HOME؛ ويمكن تجاوزها باستخدام OPENCLAW_GIT_DIR) ويحدّثها ويثبّت CLI العام من تلك النسخة المستنسخة.
  • stable -> يثبّت من npm باستخدام latest.
  • extended-stable -> يحل محدد اختيار npm العام extended-stable، ويتحقق من الحزمة المحددة بدقة، ويثبّت ذلك الإصدار الدقيق. ولا يرجع إلى محدد اختيار آخر، ويُرفض لنسخ Git المستنسخة.
  • beta -> يفضّل وسم توزيع npm ‏beta، ويرجع إلى latest عندما تكون beta مفقودة أو أقدم من الإصدار المستقر الحالي.

​
تسليم إعادة التشغيل

يشغّل المحدّث التلقائي لنواة Gateway (عند تمكينه عبر الإعدادات) مسار تحديث CLI خارج معالج طلبات Gateway النشط. تستخدم تحديثات مدير الحزم update.run لمستوى التحكم وتحديثات نسخ git المستنسخة الخاضعة للإشراف تسليم الخدمة المُدارة نفسه بدلًا من استبدال شجرة الحزم أو إعادة بناء dist/ داخل عملية Gateway النشطة: يبدأ Gateway مساعدًا منفصلًا ثم يخرج، ويشغّل ذلك المساعد openclaw update --yes --json من خارج شجرة عمليات Gateway. إذا لم يكن التسليم متاحًا، فيُرجع update.run استجابة منظّمة تتضمن أمر الصدفة الآمن المطلوب تشغيله يدويًا. تتلقى اختيارات الدعم المستقر الممتد المخزنة تلميحات للقراءة فقط عند بدء التشغيل وكل 24 ساعة عند تمكين update.checkOnStart. لا تطبّق هذه الفحوصات أي تحديث مطلقًا، ولا تبدأ عملية تسليم، ولا تعيد تشغيل Gateway، ولا تستخدم تأخير/تذبذب القناة المستقرة، ولا تستخدم وتيرة استطلاع القناة التجريبية. تظل التحديثات الصريحة في الواجهة الأمامية، والتحديثات غير المقيّدة في الواجهة الأمامية مع update.channel: "extended-stable" المخزن، والحالة عند الطلب، وعملية تسليم Gateway المُدارة الخاصة بها مدعومة. عند تثبيت خدمة Gateway مُدارة محلية وتمكين إعادة التشغيل، توقف تحديثات مدير الحزم ونسخة git العاملة الخدمة قيد التشغيل قبل استبدال شجرة الحزمة أو تعديل مخرجات النسخة العاملة/البناء. بعد ذلك، يحدّث برنامج التحديث بيانات الخدمة الوصفية، ويعيد تشغيل الخدمة، ويتحقق من Gateway المُعاد تشغيله قبل الإبلاغ عن Gateway: restarted and verified.. تتحقق تحديثات مدير الحزم أيضًا من أن Gateway المُعاد تشغيله يبلغ عن إصدار الحزمة المتوقع؛ وتتحقق تحديثات نسخة git العاملة من سلامة Gateway وجاهزية الخدمة بعد إعادة البناء. تواصل تحديثات مدير الحزم عادةً استخدام ملف Node التنفيذي المسجل في الخدمة المُدارة. إذا تعذّر على Node هذا تشغيل الإصدار المستهدف، لكن أمكن لـ Node الخاص بـ CLI الحالي تشغيله وثبت أن الخدمة تتبع الحزمة الجاري تحديثها، يستخدم تحديث مُمكّن لإعادة التشغيل Node الحالي لإنهاء العملية ويعيد كتابة بيانات الخدمة الوصفية لاستخدام بيئة التشغيل هذه. لا يستطيع --no-restart إصلاح بيانات الخدمة الوصفية، لذا يؤدي عدم تطابق بيئة التشغيل نفسه إلى التوقف قبل تعديل الحزمة. على macOS، يتحقق فحص ما بعد التحديث أيضًا من أن LaunchAgent محمّل/قيد التشغيل للملف الشخصي النشط وأن منفذ الاسترجاع المحلي المهيأ سليم. إذا كان ملف plist مثبتًا لكن launchd لا يشرف عليه، فإن OpenClaw يعيد تمهيد LaunchAgent تلقائيًا ويعيد تنفيذ فحوصات السلامة/الإصدار/ جاهزية القناة (يحمّل التمهيد الجديد مهمة RunAtLoad مباشرةً، لذا لا تؤدي الاستعادة فورًا إلى kickstart -k لـ Gateway المنشأ حديثًا). إذا ظل Gateway غير سليم، يخرج الأمر برمز غير صفري ويطبع مسار سجل إعادة التشغيل بالإضافة إلى تعليمات إعادة التشغيل وإعادة التثبيت والتراجع عن الحزمة. إذا تعذّر تنفيذ إعادة التشغيل، يطبع الأمر Gateway: restart skipped (...) أو Gateway: restart failed: ... مع تلميح يدوي لـ openclaw gateway restart. مع --no-restart، يستمر استبدال الحزمة أو إعادة بناء git، لكن الخدمة المُدارة لا تتوقف ولا تُعاد تشغيلها، لذلك يواصل Gateway قيد التشغيل استخدام الشيفرة القديمة حتى تعيد تشغيله يدويًا.

​
بنية استجابة مستوى التحكم

عند تشغيل update.run عبر مستوى تحكم Gateway على تثبيت مدير حزم أو نسخة git عاملة خاضعة للإشراف، يبلغ المعالج عن بدء التسليم بشكل منفصل عن تحديث CLI الذي يستمر بعد خروج Gateway:
  • ok: true، وresult.status: "skipped"، وresult.reason: "managed-service-handoff-started"، و handoff.status: "started": أنشأ Gateway عملية تسليم الخدمة المُدارة وجدول إعادة تشغيله كي يتمكن المساعد المنفصل من تشغيل openclaw update --yes --json خارج عملية الخدمة الحية.
  • ok: false، وresult.reason: "managed-service-handoff-unavailable"، و handoff.status: "unavailable": تعذّر على OpenClaw العثور على حدود خدمة خاضعة للإشراف وهوية خدمة دائمة لإجراء تسليم آمن (على سبيل المثال، تتطلب عملية تسليم systemd هوية وحدة OPENCLAW_SYSTEMD_UNIT، وليس مجرد مؤشرات عملية systemd المحيطة). تتضمن الاستجابة handoff.command، وهو أمر الصدفة المطلوب تشغيله من خارج Gateway.
  • ok: false، وresult.reason: "managed-service-handoff-failed": حاول Gateway إنشاء عملية التسليم لكنه لم يتمكن من إنشاء المساعد المنفصل.
تُكتب حمولة sentinel قبل خروج Gateway، ويحدّث تسليم CLI مؤشر إعادة التشغيل نفسه بعد اكتمال فحوصات سلامة إعادة تشغيل الخدمة المُدارة. أثناء التسليم، يمكن أن يحمل المؤشر stats.reason: "restart-health-pending" من دون متابعة نجاح؛ ويستطلعه Gateway المُعاد تشغيله ويطلق المتابعة فقط بعد أن يتحقق CLI من سلامة الخدمة ويعيد كتابة المؤشر بنتيجة ok النهائية. يعرض openclaw status وopenclaw status --all صف Update restart بينما يكون ذلك المؤشر معلقًا أو فاشلًا، ويحدّث update.status أحدث مؤشر ويعيده.

​
تدفق نسخة Git العاملة

​
اختيار القناة

  • stable: اسحب أحدث وسم غير تجريبي، ثم نفّذ البناء وأداة doctor.
  • beta: فضّل أحدث وسم -beta، مع الرجوع إلى أحدث وسم مستقر عندما تكون القناة التجريبية مفقودة أو أقدم.
  • dev: اسحب main، ثم اجلب التغييرات ونفّذ إعادة الأساس.
  • extended-stable: غير مدعوم لنسخ Git العاملة؛ لا يحدث أي تعديل للنسخة العاملة.

​
خطوات التحديث

1

التحقق من نظافة شجرة العمل

يتطلب عدم وجود تغييرات غير ملتزم بها.
2

تبديل القناة

ينتقل إلى القناة المحددة (وسم أو فرع).
3

جلب المصدر الرئيسي

للتطوير فقط.
4

البناء التمهيدي (للتطوير فقط)

يشغّل بناء TypeScript في شجرة عمل مؤقتة. إذا فشل الطرف، يرجع عبر ما يصل إلى 10 التزامات للعثور على أحدث التزام قابل للبناء. عيّن OPENCLAW_UPDATE_PREFLIGHT_LINT=1 لتشغيل التدقيق أيضًا أثناء هذا الفحص التمهيدي؛ يعمل التدقيق في وضع تسلسلي مقيّد لأن مضيفي تحديث المستخدمين غالبًا ما يكونون أصغر من مشغّلات CI.
5

إعادة الأساس

ينفّذ إعادة الأساس على الالتزام المحدد (للتطوير فقط).
6

تثبيت التبعيات

يستخدم مدير حزم المستودع. بالنسبة إلى نسخ pnpm العاملة، يمهّد برنامج التحديث pnpm عند الطلب (عبر corepack أولًا، ثم بديل مؤقت npm install pnpm@11) بدلًا من تشغيل npm run build داخل مساحة عمل pnpm. إذا استمر فشل تمهيد pnpm، يتوقف برنامج التحديث مبكرًا مع خطأ خاص بمدير الحزم بدلًا من محاولة npm run build في النسخة العاملة.
7

بناء واجهة التحكم

يبني Gateway وواجهة التحكم.
8

تشغيل doctor

يُشغّل openclaw doctor بوصفه فحص التحديث الآمن النهائي.
9

مزامنة plugins

يزامن plugins مع القناة النشطة. يستخدم التطوير plugins المضمّنة؛ وتستخدم القناتان المستقرة والتجريبية npm. يحدّث عمليات تثبيت plugins المتتبعة.

​
تفاصيل مزامنة plugins

على القناة التجريبية، تحاول عمليات تثبيت plugins المتتبعة من npm وClawHub التي تتبع مسار الافتراضي/الأحدث إصدار @beta من plugin أولًا. إذا لم يكن لدى plugin إصدار تجريبي، يرجع OpenClaw إلى مواصفة الافتراضي/الأحدث المسجلة ويبلغ عن تحذير. بالنسبة إلى plugins من npm، يرجع OpenClaw أيضًا عندما تكون الحزمة التجريبية موجودة لكنها تفشل في التحقق من صحة التثبيت. لا تؤدي تحذيرات الرجوع هذه إلى فشل تحديث النواة. لا تُعاد كتابة الإصدارات الدقيقة والوسوم الصريحة مطلقًا.
إذا حُل تحديث plugin من npm مثبت بإصدار دقيق إلى عنصر تختلف سلامته عن سجل التثبيت المخزن، فإن openclaw update يُجهض تحديث عنصر plugin هذا بدلًا من تثبيته. أعد تثبيت plugin أو تحديثه صراحةً فقط بعد التحقق من ثقتك بالعنصر الجديد.
يُبلّغ عن إخفاقات مزامنة plugins بعد التحديث التي تقتصر على plugin مُدار ويمكن لمسار المزامنة تجاوزها (مثل تعذّر الوصول إلى سجل npm لـ plugin غير أساسي) بوصفها تحذيرات بعد نجاح تحديث النواة. تحتفظ نتيجة JSON بقيمة status: "ok" للتحديث في المستوى الأعلى، وتبلغ عن postUpdate.plugins.status: "warning" مع إرشادات openclaw update repair وopenclaw plugins inspect <id> --runtime --json. تظل استثناءات برنامج التحديث أو المزامنة غير المتوقعة مؤدية إلى فشل نتيجة التحديث. أصلح خطأ تثبيت plugin أو تحديثه، ثم أعد تشغيل openclaw update repair. عندما يترك تحديث فاشل plugin مُدارًا غير قابل للاستخدام، يعطّل OpenClaw إدخال بيئة التشغيل الخاص به ويعيد تعيين الفتحات النشطة من دون تغيير سياسة plugins.allow أو plugins.deny التي وضعها المشغّل.بعد خطوة مزامنة كل plugin، يشغّل openclaw update مرحلة تقارب ما بعد النواة إلزامية قبل إعادة تشغيل Gateway: يصلح حمولات plugins المهيأة المفقودة، ويتحقق من كل سجل تثبيت متتبّع نشط على القرص، ويتحقق ساكنًا من إمكانية تحليل package.json الخاص به (ومن وجود أي main معلن صراحةً). تعيد إخفاقات هذه المرحلة، وكذلك لقطة تهيئة غير صالحة، القيمة postUpdate.plugins.status: "error" وتغيّر قيمة status للتحديث في المستوى الأعلى إلى "error"، بحيث يخرج openclaw update برمز غير صفري ولا يُعاد تشغيل Gateway بمجموعة plugins غير متحقق منها. يتضمن الخطأ أسطر postUpdate.plugins.warnings[].guidance منظّمة تشير إلى openclaw update repair وopenclaw plugins inspect <id> --runtime --json. تُتخطى هنا إدخالات plugins المعطلة والسجلات التي ليست أهداف مزامنة رسمية مرتبطة بمصدر موثوق (بما يعكس سياسة skipDisabledPlugins التي يستخدمها فحص الحمولة المفقودة)، لذا لا يمكن لسجل plugin معطل قديم أن يمنع تحديثًا صالحًا بخلاف ذلك.عند بدء Gateway المحدّث، يكون تحميل plugins للتحقق فقط: لا يشغّل بدء التشغيل مديري الحزم ولا يعدّل أشجار التبعيات. تُسلّم عمليات إعادة تشغيل update.run الخاصة بمدير الحزم إلى مسار الخدمة المُدارة في CLI، بحيث يحدث تبديل الحزمة خارج عملية Gateway القديمة وتحدد فحوصات سلامة الخدمة ما إذا كان يمكن الإبلاغ عن اكتمال التحديث.
بعد نجاح تحديث النواة ذات الدعم المستقر الممتد، تستهدف سلامة plugins وتقاربها بعد النواة plugins الرسمية المؤهلة من npm بالإصدار الدقيق المثبت للنواة. بالنسبة إلى نية الافتراضي/latest، لا يستعلم OpenClaw عن @extended-stable الخاصة بـ plugin ولا يرجع إلى latest في npm؛ بل يستنتج إصدار الحزمة من النواة المثبتة. تحتفظ عمليات تثبيت الإصدار الصريحة، والوسوم الصريحة غير latest، وحزم الجهات الخارجية، والمصادر غير التابعة لـ npm بنيتها الحالية. بالنسبة إلى عمليات تثبيت مدير الحزم، يحل openclaw update إصدار الحزمة المستهدف قبل استدعاء مدير الحزم. تستخدم عمليات التثبيت العامة في npm تثبيتًا مرحليًا: يثبت OpenClaw الحزمة الجديدة في بادئة npm مؤقتة، ويتيح للحزمة المرشحة التحقق من إصدار Node للمضيف أثناء preinstall، ويتحقق هناك من مخزون dist المضمّن في الحزمة. يظل حاجز إكمال مضمّن خارج ذلك المخزون حتى ينجح preinstall، بحيث تتوقف أيضًا برامج إدارة الحزم التي تتخطى نصوص دورة الحياة قبل التنشيط. في npm 12 والإصدارات الأحدث، لا يوافق برنامج التحديث إلا على دورة حياة OpenClaw المرشحة؛ وتظل نصوص التبعيات المتعدية محظورة. بعد ذلك، يبدّل OpenClaw شجرة الحزمة النظيفة إلى البادئة العامة الفعلية. إذا فشل التحقق، فلا تعمل أداة doctor بعد التحديث ولا مزامنة plugins ولا إعادة التشغيل من الشجرة المشبوهة. حتى عندما يطابق الإصدار المثبت الهدف بالفعل، يحدّث الأمر تثبيت الحزمة العامة، ثم يشغّل مزامنة plugins وتحديث إكمال أوامر النواة وأعمال إعادة التشغيل. يحافظ ذلك على محاذاة البرامج الجانبية المضمّنة في الحزمة وسجلات plugins المملوكة للقناة مع إصدار OpenClaw المثبت، مع ترك عمليات إعادة بناء إكمال أوامر plugins الكاملة لعمليات تشغيل openclaw completion --write-state الصريحة.

​
ذو صلة