جارٍ التحديث

حافظ على تحديث OpenClaw.

لاستبدال صور Docker وPodman وKubernetes، راجع ترقية صور الحاويات. ينفّذ Gateway أعمال الترقية الآمنة عند بدء التشغيل قبل الجاهزية، ويخرج إذا كانت الحالة الموصولة تحتاج إلى إصلاح يدوي.

موصى به: openclaw update

يكتشف نوع التثبيت لديك (npm أو pnpm أو Bun أو git)، ويجلب أحدث إصدار، ويشغّل openclaw doctor، ثم يعيد تشغيل Gateway.

openclaw update

بدّل القنوات أو استهدف إصدارًا محددًا:

openclaw update --channel betaopenclaw update --channel extended-stableopenclaw update --channel devopenclaw update --dry-run   # معاينة من دون تطبيق

لا يتضمن openclaw update علامة --verbose (لكن أداة التثبيت تتضمنها). لأغراض التشخيص، استخدم --dry-run لمعاينة الإجراءات المخططة، أو --json للحصول على نتائج منظّمة، أو openclaw update status --json لفحص حالة القناة والتوافر.

يفضّل --channel beta وسم التوزيع beta في npm، لكنه يعود إلى stable/latest عندما يكون وسم beta مفقودًا أو يكون إصداره أقدم من أحدث إصدار مستقر. استخدم بدلًا منه --tag beta لتحديث حزمة لمرة واحدة مثبّت على وسم توزيع beta الخام في npm.

يقتصر --channel extended-stable على الحزمة فقط، ويظل التثبيت في الواجهة الأمامية فقط. يقرأ OpenClaw محدّد npm العام extended-stable، ويتحقق من الحزمة الدقيقة المحددة، ثم يثبّت ذلك الإصدار بعينه. يؤدي فقدان بيانات السجل أو عدم اتساقها إلى الإخفاق الآمن؛ ولا يعود مطلقًا إلى latest. إذا كان الإصدار المحدد أقدم من الإصدار المثبّت، يظل تأكيد الرجوع إلى إصدار أقدم المعتاد ساريًا. يحفظ CLI القناة بعد نجاح تحديث النواة؛ أما تنفيذ npm install -g openclaw@extended-stable مباشرةً فلا يحدّث update.channel. بعد تبديل النواة، تتقارب Plugins الرسمية المؤهلة من npm ذات النية الافتراضية/المجرّدة أو نية latest إلى إصدار النواة الدقيق نفسه. تظل التثبيتات الدقيقة والوسوم الصريحة غير latest وPlugins التابعة لجهات خارجية والمصادر غير npm دون تغيير. تحتفظ تثبيتات الكتالوج المنشأة بواسطة إصدارات OpenClaw الحالية بتلك النية الافتراضية. تظل السجلات الأقدم التي لا تحتوي إلا على إصدار دقيق مثبّتة لأن OpenClaw لا يستطيع التمييز بأمان بين تثبيت تلقائي قديم وتثبيت أجراه المستخدم؛ شغّل openclaw plugins update @openclaw/name مرة واحدة على قناة extended-stable لإعادة إشراك ذلك Plugin في تتبع إصدار النواة الدقيق.

يوفّر --channel dev نسخة عمل GitHub متحركة ودائمة من main. ولتحديث حزمة لمرة واحدة، يعيّن --tag main مواصفة الحزمة github:openclaw/openclaw#main ويثبّتها مباشرةً عبر مدير الحزم المستهدف (npm/pnpm/bun).

بالنسبة إلى Plugins المُدارة، يُعد غياب إصدار beta تحذيرًا لا إخفاقًا: يمكن أن ينجح تحديث النواة مع عودة Plugin إلى الإصدار الافتراضي/latest المسجّل له.

راجع قنوات الإصدار لمعرفة دلالات القنوات.

التبديل بين تثبيتات npm وgit

استخدم القنوات لتغيير نوع التثبيت. يحافظ محدّث البرنامج على الحالة والإعدادات وبيانات الاعتماد ومساحة العمل في ~/.openclaw؛ ولا يغيّر سوى تثبيت شفرة OpenClaw الذي يستخدمه CLI وGateway.

# تثبيت حزمة npm -> نسخة عمل git قابلة للتحريرopenclaw update --channel dev # نسخة عمل git -> تثبيت حزمة npmopenclaw update --channel stable

عاين تبديل وضع التثبيت أولًا:

openclaw update --channel dev --dry-runopenclaw update --channel stable --dry-run

يضمن dev وجود نسخة عمل git، ويبنيها، ويثبّت CLI العام من تلك النسخة. تستخدم القنوات stable وextended-stable وbeta تثبيتات الحزم. يُرفض extended-stable في نسخة عمل git من دون تعديلها أو تحويلها. إذا كان Gateway مثبتًا بالفعل، فإن openclaw update يحدّث بيانات الخدمة الوصفية ويعيد تشغيلها ما لم تمرّر --no-restart.

بالنسبة إلى تثبيتات الحزم التي تستخدم خدمة Gateway مُدارة، يستهدف openclaw update جذر الحزمة الذي تستخدمه تلك الخدمة. إذا كان أمر الصدفة openclaw صادرًا من تثبيت مختلف، يطبع محدّث البرنامج كلا الجذرين ومسار Node للخدمة المُدارة، ويتحقق من إصدار Node هذا مقابل متطلب engines.node للإصدار المستهدف قبل استبدال الحزمة.

بديل: إعادة تشغيل أداة التثبيت

curl -fsSL https://openclaw.ai/install.sh | bash

أضف --no-onboard لتخطّي الإعداد الأولي. لفرض نوع تثبيت محدد، مرّر --install-method git --no-onboard أو --install-method npm --no-onboard.

إذا أخفق openclaw update بعد مرحلة تثبيت حزمة npm، فأعد تشغيل أداة التثبيت بدلًا منه. فهي لا تستدعي محدّث البرنامج؛ بل تنفّذ تثبيت الحزمة العام مباشرةً، ويمكنها استعادة تثبيت npm محدّث جزئيًا.

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

ثبّت الاستعادة على إصدار أو وسم توزيع محدد باستخدام --version:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>

بديل: npm أو pnpm أو bun يدويًا

npm i -g openclaw@latest

يفضّل استخدام openclaw update للتثبيتات الخاضعة للإشراف: إذ يمكنه تنسيق تبديل الحزمة مع خدمة Gateway قيد التشغيل. إذا أجريت تحديثًا يدويًا في تثبيت خاضع للإشراف، فأوقف Gateway المُدار أولًا. تستبدل مديري الحزم الملفات في مواضعها، وإلا فقد يحاول Gateway قيد التشغيل تحميل ملفات النواة أو Plugin في أثناء التبديل. أعد تشغيل Gateway بعد انتهاء مدير الحزم كي يستخدم التثبيت الجديد.

بالنسبة إلى تثبيت عام على مستوى نظام Linux مملوك للمستخدم الجذر، إذا أخفق openclaw update بسبب EACCES، فاستعده باستخدام npm الخاص بالنظام مع إبقاء Gateway متوقفًا خلال الاستبدال اليدوي. استخدم علامات ملف التعريف/البيئة نفسها التي تستخدمها عادةً لذلك Gateway. استبدل /usr/bin/npm بـ npm الخاص بالنظام الذي يملك البادئة العامة المملوكة للمستخدم الجذر على مضيفك:

openclaw gateway stopsudo /usr/bin/npm i -g openclaw@latestopenclaw gateway install --forceopenclaw gateway restart

ثم تحقّق:

openclaw --versioncurl -fsS http://127.0.0.1:18789/readyzopenclaw plugins list --jsonopenclaw gateway status --deep --jsonopenclaw doctor --lint --json

عندما يدير openclaw update تثبيت npm عامًا، فإنه يثبّت الهدف أولًا في بادئة npm مؤقتة. تتحقق الحزمة المرشحة من إصدار Node على المضيف أثناء preinstall؛ وعندها فقط يتحقق OpenClaw من مخزون dist المضمّن في الحزمة ويبدّل شجرة الحزمة النظيفة إلى البادئة العامة الفعلية. يُحذف حارس إكمال التحزيم من المخزون المتوقع ولا تتم إزالته إلا بعد نجاح preinstall، بحيث تفشل نصوص دورة الحياة المتخطاة أيضًا قبل التبديل. في npm 12 والإصدارات الأحدث، لا يوافق محدّث البرنامج إلا على دورة حياة OpenClaw المرشحة؛ وتظل نصوص التبعيات المتعدية محظورة. يمنع ذلك npm من تراكب حزمة جديدة فوق ملفات قديمة متبقية من الحزمة السابقة. إذا أخفق أمر التثبيت، يعيد OpenClaw المحاولة مرة واحدة باستخدام --omit=optional، ما يساعد المضيفات التي لا يمكن فيها تجميع التبعيات الاختيارية الأصلية.

تمسح أيضًا أوامر تحديث npm وتحديث Plugin التي يديرها OpenClaw حجر سلسلة التوريد min-release-age الخاص بـ npm (أو مفتاح الإعداد الأقدم before) لعملية npm الفرعية. توجد هذه السياسة للحماية العامة، لكن تحديث OpenClaw الصريح يعني «ثبّت الإصدار المحدد الآن».

pnpm add -g openclaw@latest

إذا ثبّت pnpm 11 إصدار OpenClaw 2026.7.1، فنفّذ ذلك الأمر اليدوي مرة واحدة. يسبق ذلك الإصدار تخطيط الحزم العامة المعزولة في pnpm 11، لذلك قد يخطئ محدّثه ويعتبر تثبيت npm آخر هو CLI قيد التشغيل. تحتفظ الإصدارات اللاحقة بملكية pnpm وتتبع جذر الحزمة البديلة أثناء التحديثات. كما أنها تستخدم دليل الملفات التنفيذية العام الذي يبلّغ عنه المدير المالك، وتتوقف قبل التعديل عندما يبلّغ أمر pnpm المتاح عن جذر عام أو إصدار رئيسي مختلف، أو عندما تكون الحزمة المستدعية يتيمة أو لا تكون تثبيت OpenClaw النشط الوحيد هناك.

إذا شارك OpenClaw مجموعة تثبيت عامة في pnpm 11 مع حزمة أخرى، يتوقف محدّث البرنامج التلقائي قبل تغيير المجموعة. حدّث المجموعة الأصلية المفصولة بفواصل يدويًا حتى تظل حزمها الشقيقة وسياسة بنائها سليمة.

bun add -g openclaw@latest

موضوعات متقدمة لتثبيت npm

ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp

محدّث البرنامج التلقائي

معطّل افتراضيًا. فعّله في ~/.openclaw/openclaw.json:

{  update: {    channel: "stable",    auto: {      enabled: true,      stableDelayHours: 6,      stableJitterHours: 12,      betaCheckIntervalHours: 1,    },  },}

يسجّل Gateway أيضًا تلميح تحديث عند بدء التشغيل (يمكن تعطيله باستخدام update.checkOnStart: false). تستخدم تحديدات extended-stable المخزنة مسار التلميح للقراءة فقط هذا وفاصل التلميح الحالي البالغ 24 ساعة، لكنها لا تستدعي مطلقًا التثبيت التلقائي أو التسليم أو إعادة التشغيل أو تأخير/تفاوت stable أو استطلاع beta. للرجوع إلى إصدار أقدم أو الاستعادة من حادث، اضبط OPENCLAW_NO_AUTO_UPDATE=1 في بيئة Gateway لمنع عمليات التطبيق التلقائية حتى عند إعداد update.auto.enabled. يمكن أن تستمر تلميحات التحديث عند بدء التشغيل ما لم يُعطّل update.checkOnStart أيضًا.

لا تستبدل تحديثات مدير الحزم المطلوبة عبر مستوى تحكم Gateway المباشر (update.run) شجرة الحزمة داخل عملية Gateway قيد التشغيل. في تثبيتات الخدمات المُدارة، يبدأ Gateway عملية تسليم منفصلة، ثم يخرج، ويترك لمسار CLI المعتاد openclaw update --yes --json إيقاف الخدمة واستبدال الحزمة وتحديث بيانات الخدمة الوصفية وإعادة تشغيلها والتحقق من إصدار Gateway وإمكانية الوصول إليه واستعادة LaunchAgent على macOS المثبّت لكنه غير المحمّل، متى أمكن. إذا تعذّر على Gateway إجراء ذلك التسليم بأمان، فإن update.run يعرض أمر صدفة آمنًا بدلًا من تشغيل مدير الحزم داخل العملية.

تعرض بطاقة التحديث في الشريط الجانبي لواجهة التحكم تحديث Gateway عندما تبدأ تدفق update.run هذا مباشرةً. ويشمل ذلك واجهة التحكم المستضافة في المتصفح، وGateways البعيدة، وGateways المحلية المُدارة يدويًا.

في تطبيق macOS الموقّع، تغيّر Gateway محلية يملكها التطبيق تلك البطاقة إلى تحديث تطبيق Mac وGateway. يحدّث Sparkle التطبيق أولًا؛ وبعد إعادة التشغيل، يشغّل التطبيق openclaw update --tag <app-version> --json، ويعيد تشغيل Gateway الخاصة به، ويتحقق من سلامتها في نافذة تقدم بأسلوب الإعداد. لا تظهر النافذة إلا عندما تحتاج Gateway المُدارة تلك إلى تحديث أو إصلاح أو تثبيت؛ أما تحديثات التطبيق فقط فتعيد التشغيل مباشرةً إلى التطبيق. تظل تفاصيل الفشل ظاهرة مع إجراءات إعادة المحاولة، ودليل التحديث، و Discord. لا يستخدم التطبيق مطلقًا هذا المسار المنسّق مع Gateway بعيدة أو مُدارة خارجيًا، ولا يرجع مطلقًا Gateway أحدث إلى إصدار أقدم، ولا يتجاوز مطلقًا تثبيت قناة extended-stable.

عند نجاح التحديث، يضع التطبيق حدث ترحيب لمرة واحدة في قائمة الانتظار لأحدث جلسة مباشرة من المستوى الأعلى شهدت تفاعلًا حقيقيًا مع مستخدم/قناة. لا تغيّر عمليات Cron، ولا Heartbeat، ولا تحديثات الجلسات التي تجري في الخلفية فقط هذا الاختيار. في الوضع البعيد، لا يحدّث التطبيق سوى وقت تشغيل Node المحلي على Mac ويرسل الحدث فقط عندما تكون Gateway البعيدة المتصلة حديثة بقدر التطبيق على الأقل.

بعد التحديث

openclaw doctor

openclaw gateway restart

openclaw health

التراجع

يتألف التراجع من مستويين:

1. أعد تثبيت إصدار أقدم من شيفرة OpenClaw مع الاحتفاظ بالحالة الحالية.
2. استعد الحالة السابقة للتحديث فقط عندما يتعذر على الشيفرة الأقدم استخدام إعدادات أو قاعدة بيانات جرى ترحيلها.

ابدأ بالتراجع عن الشيفرة فقط. تؤدي استعادة الحالة إلى فقدان التغييرات التي أُجريت بعد النسخة الاحتياطية.

قبل التحديث: إنشاء نسخة احتياطية متحقق منها

يحافظ openclaw update على نسخة تلقائية من الإعدادات قبل التحديث، لكنه لا ينشئ نقطة استعادة كاملة للحالة. قبل إجراء تحديث مهم، أنشئ واحدة صراحةً:

mkdir -p ~/Backups/openclawopenclaw backup create --output ~/Backups/openclaw --verify

يسجل بيان الأرشيف إصدار OpenClaw ومسارات المصدر المضمّنة في النسخة الاحتياطية. قد يحتوي الأرشيف على بيانات اعتماد وملفات تعريف مصادقة وحالة القنوات، لذا خزّنه بأذونات المالك فقط وبمستوى الحماية نفسه المطبق على دليل الحالة المباشر. راجع النسخ الاحتياطي لمعرفة الملفات المضمّنة والمستبعدة عمدًا.

لإنشاء نقطة استعادة مطابقة بايتًا ببايت تشمل العناصر المؤقتة التي يستبعدها الأرشيف المحمول، أوقف Gateway واستخدم لقطة لنظام الملفات أو وحدة التخزين أو الجهاز الافتراضي توفرها منصتك.

التراجع عن تثبيت حزمة

اعرض الإصدارات المنشورة، ثم عاين الإصدار المعروف بسلامته وثبّته:

npm view openclaw versions --jsonopenclaw update --tag <known-good-version> --dry-runopenclaw update --tag <known-good-version>

يُفضّل openclaw update --tag على التثبيت المباشر باستخدام مدير الحزم. فهو يكتشف الرجوع إلى إصدار أقدم، ويطلب التأكيد، ويجري تقارب Plugins المُدارة وفحوص التوافق مع الإصدار الهدف المثبّت، ويحدّث بيانات الخدمة الوصفية، ويعيد تشغيل Gateway، ويتحقق من الإصدار قيد التشغيل. إذا كانت القناة المخزنة هي extended-stable، فاستخدم --channel stable --tag <known-good-version> لأن وسوم الاستخدام الواحد الدقيقة لا يمكن دمجها مع محدد extended-stable.

تجهّز تحديثات الحزم الإصدار المرشح وتتحقق منه قبل التفعيل. إذا فشل تبديل نظام الملفات أو استبدال وسيط الأمر، يستعيد OpenClaw الحزمة القديمة تلقائيًا. وبعد نجاح التبديل، إذا فشل فحص سلامة Gateway لاحقًا، يُبلَّغ عن الإصدار السابق وتُعرض تعليمات التراجع اليدوي بدلًا من استبدال الحزمة تلقائيًا مرة أخرى.

إذا كان مسار تحديث CLI غير متاح، فاستخدم مدير الحزم ونطاق التثبيت نفسيهما اللذين يديران Gateway الحالية:

openclaw gateway stopnpm i -g openclaw@<known-good-version>openclaw gateway install --forceopenclaw gateway restart

استبدل npm بـ pnpm أو bun عندما يكون ذلك المدير مسؤولًا عن التثبيت. أثناء التعافي من الحوادث، امنع أداة التحديث التلقائي المفعّلة من تطبيق إصدار أحدث فورًا من خلال ضبط OPENCLAW_NO_AUTO_UPDATE=1 في بيئة Gateway.

التراجع عن نسخة مصدر مستخرجة

استخدم نسخة مستخرجة نظيفة وحدد وسمًا أو التزامًا معروفًا بسلامته:

git fetch --all --tagsgit checkout --detach <known-good-tag-or-commit>pnpm install && pnpm buildopenclaw gateway restart

للعودة إلى أحدث إصدار: git checkout main && git pull.

تعيد أداة التحديث نسخة git المستخرجة تلقائيًا إلى فرعها و SHA السابقين عندما يفشل تثبيت التبعيات أو البناء أو بناء واجهة المستخدم أو أداة الفحص بعد بدء تحديث git. يظل الاستخراج اليدوي مطلوبًا عندما تختار التزامًا أقدم عمدًا.

الرجوع إلى إصدار أقدم عبر ترحيل SQLite للجلسات

قبل تشغيل إصدار أقدم من OpenClaw يعتمد على الملفات، استخدم CLI الحالي لاستعادة عناصر نصوص الجلسات القديمة المؤرشفة:

openclaw gateway stopopenclaw doctor --session-sqlite restore --session-sqlite-all-agents

لا يؤدي ذلك إلى حذف بيانات SQLite. الجلسات التي أُنشئت بعد ترحيل SQLite لا توجد إلا في SQLite ولن تظهر لوقت التشغيل الأقدم. راجع الرجوع إلى إصدار أقدم بعد ترحيل SQLite للجلسات.

استعادة الحالة عند الضرورة فقط

إذا تعذر على الشيفرة الأقدم قراءة إعدادات أحدث أو مخطط قاعدة بيانات أحدث، فأوقف Gateway واستعد لقطة نظام الملفات أو وحدة التخزين أو الجهاز الافتراضي المتحقق منها والمأخوذة قبل التحديث. احتفظ بالحالة الحالية بشكل منفصل قبل الاستعادة لأن ذلك يزيل التغييرات التي أُجريت بعد اللقطة.

تدعم أرشيفات openclaw backup create الشاملة الإنشاء والتحقق، لكنها لا تدعم تفعيل الأرشيف بالكامل في موضعه. استخرج أرشيفًا شاملًا إلى دليل تجهيز، واستخدم تعيين المصدر إلى الأرشيف في manifest.json لإجراء استعادة دون اتصال. وبالمثل، يكتب openclaw backup sqlite restore قاعدة بيانات متحققًا منها إلى هدف جديد؛ ويظل تفعيل ذلك الهدف خطوة صريحة ينفذها المشغّل دون اتصال.

التحقق من التراجع

openclaw --versionopenclaw healthopenclaw plugins list --jsonopenclaw gateway status --deep --jsonopenclaw doctor --lint --json

إذا تعذّر عليك المتابعة

• شغّل openclaw doctor مرة أخرى واقرأ المخرجات بعناية.
• بالنسبة إلى openclaw update --channel dev في نسخ المصدر المستخرجة، تهيّئ أداة التحديث pnpm تلقائيًا عند الحاجة. إذا ظهر خطأ في تهيئة pnpm/corepack، فثبّت pnpm يدويًا (أو أعد تمكين corepack) ثم أعد تشغيل التحديث.
• راجع: استكشاف الأخطاء وإصلاحها
• اطلب المساعدة في Discord: https://discord.gg/clawd

ذو صلة

• نظرة عامة على التثبيت: جميع طرق التثبيت.
• أداة الفحص: فحوص السلامة بعد التحديثات.
• الترحيل: أدلة الترحيل بين الإصدارات الرئيسية.