---
read_when:
    - تريد تحديث نسخة عمل من المصدر بأمان
    - أنت تستكشف أخطاء مخرجات `openclaw update` أو خياراته
    - تحتاج إلى فهم سلوك الاختصار لـ `--update`
summary: مرجع CLI لـ `openclaw update` (تحديث المصدر شبه الآمن + إعادة التشغيل التلقائية لـ Gateway)
title: تحديث
x-i18n:
    generated_at: "2026-05-12T08:45:54Z"
    model: gpt-5.5
    provider: openai
    source_hash: 93244af800aaa53c55a52f9593a7727910aa91acac9d1e34e89c39a95b133461
    source_path: cli/update.md
    workflow: 16
---

# `openclaw update`

حدّث OpenClaw بأمان وبدّل بين قنوات stable/beta/dev.

إذا ثبّت عبر **npm/pnpm/bun** (تثبيت عام، بلا بيانات git وصفية)،
تتم التحديثات عبر مسار مدير الحزم في [التحديث](/ar/install/updating).

## الاستخدام

```bash
openclaw update
openclaw update status
openclaw update wizard
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --tag main
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --json
openclaw --update
```

## الخيارات

- `--no-restart`: تخطَّ إعادة تشغيل خدمة Gateway بعد نجاح التحديث. تحديثات مدير الحزم التي تعيد تشغيل Gateway تتحقق من أن الخدمة المعاد تشغيلها تبلغ عن الإصدار المحدّث المتوقع قبل نجاح الأمر.
- `--channel <stable|beta|dev>`: يضبط قناة التحديث (git + npm؛ تُحفظ في الإعدادات).
- `--tag <dist-tag|version|spec>`: يتجاوز هدف الحزمة لهذا التحديث فقط. في تثبيتات الحزم، يتم تعيين `main` إلى `github:openclaw/openclaw#main`.
- `--dry-run`: يعاين إجراءات التحديث المخطط لها (تدفق القناة/الوسم/الهدف/إعادة التشغيل) من دون كتابة الإعدادات أو التثبيت أو مزامنة المكونات الإضافية أو إعادة التشغيل.
- `--json`: يطبع JSON قابلًا للقراءة آليًا من نوع `UpdateRunResult`، بما في ذلك
  `postUpdate.plugins.warnings` عندما تحتاج المكونات الإضافية المُدارة التالفة أو غير القابلة للتحميل
  إلى إصلاح بعد نجاح تحديث النواة، وتفاصيل الرجوع الاحتياطي للمكونات الإضافية في قناة beta
  عندما لا يتوفر إصدار beta لمكوّن إضافي، و`postUpdate.plugins.integrityDrifts`
  عند اكتشاف انحراف في أثر حزمة npm للمكوّن الإضافي أثناء مزامنة المكونات الإضافية بعد التحديث.
- `--timeout <seconds>`: مهلة لكل خطوة (القيمة الافتراضية 1800s).
- `--yes`: يتخطى مطالبات التأكيد (مثل تأكيد الرجوع إلى إصدار أقدم).

لا يحتوي `openclaw update` على علم `--verbose`. استخدم `--dry-run` لمعاينة
إجراءات القناة/الوسم/التثبيت/إعادة التشغيل المخطط لها، و`--json` للنتائج
القابلة للقراءة آليًا، و`openclaw update status --json` عندما تحتاج فقط إلى تفاصيل
القناة والتوفر. إذا كنت تصحح سجلات Gateway حول تحديث،
فإن إسهاب وحدة التحكم ومستوى سجل الملفات منفصلان: يؤثر `--verbose` الخاص بـ Gateway
في خرج الطرفية/WebSocket، بينما تتطلب سجلات الملفات `logging.level: "debug"` أو
`"trace"` في الإعدادات. راجع [تسجيل Gateway](/ar/gateway/logging).

<Note>
في وضع Nix ‏(`OPENCLAW_NIX_MODE=1`)، تكون تشغيلات `openclaw update` التي تُحدِث تغييرات معطلة. حدّث مصدر Nix أو مُدخل flake لهذا التثبيت بدلًا من ذلك؛ بالنسبة إلى nix-openclaw، استخدم [البدء السريع](https://github.com/openclaw/nix-openclaw#quick-start) المعتمد على الوكيل أولًا. يبقى `openclaw update status` و`openclaw update --dry-run` للقراءة فقط.
</Note>

<Warning>
تتطلب الرجوعات إلى إصدار أقدم تأكيدًا لأن الإصدارات الأقدم قد تكسر الإعدادات.
</Warning>

## `update status`

يعرض قناة التحديث النشطة + وسم/فرع/SHA الخاص بـ git (لنسخ المصدر)، إضافة إلى توفر التحديث.

```bash
openclaw update status
openclaw update status --json
openclaw update status --timeout 10
```

الخيارات:

- `--json`: يطبع JSON للحالة قابلًا للقراءة آليًا.
- `--timeout <seconds>`: مهلة الفحوصات (القيمة الافتراضية 3s).

## `update wizard`

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

الخيارات:

- `--timeout <seconds>`: مهلة لكل خطوة تحديث (القيمة الافتراضية `1800`)

## ما الذي يفعله

عندما تبدّل القنوات صراحةً (`--channel ...`)، يبقي OpenClaw أيضًا
طريقة التثبيت متوافقة:

- `dev` → يضمن وجود نسخة git (الافتراضي: `~/openclaw`، ويمكن تجاوزها بـ `OPENCLAW_GIT_DIR`)،
  ويحدّثها، ويثبّت CLI العام من تلك النسخة.
- `stable` → يثبّت من npm باستخدام `latest`.
- `beta` → يفضّل وسم توزيع npm ‏`beta`، لكنه يرجع إلى `latest` عندما تكون beta
  مفقودة أو أقدم من الإصدار المستقر الحالي.

محدّث نواة Gateway التلقائي (عند تمكينه عبر الإعدادات) يشغّل مسار تحديث CLI
خارج معالج طلب Gateway الحي. تحديثات مدير الحزم `update.run` في مستوى التحكم
تفرض إعادة تشغيل تحديث غير مؤجلة وبلا فترة تهدئة بعد تبديل الحزمة،
لأن عملية Gateway القديمة قد لا تزال تحتوي على أجزاء في الذاكرة تشير إلى
ملفات أزالتها الحزمة الجديدة.

بالنسبة إلى تثبيتات مدير الحزم، يحل `openclaw update` إصدار الحزمة الهدف
قبل استدعاء مدير الحزم. تستخدم تثبيتات npm العامة تثبيتًا مرحليًا:
يثبّت OpenClaw الحزمة الجديدة في بادئة npm مؤقتة، ويتحقق من مخزون `dist`
المعبأ هناك، ثم يبدّل شجرة الحزمة النظيفة تلك إلى البادئة العامة الحقيقية.
إذا فشل التحقق، لا يعمل doctor بعد التحديث ولا مزامنة المكونات الإضافية ولا
إعادة التشغيل من الشجرة المشكوك فيها. حتى عندما يطابق الإصدار المثبت
الهدف بالفعل، ينعش الأمر تثبيت الحزمة العامة، ثم يشغّل مزامنة المكونات الإضافية،
وتحديث إكمال أوامر النواة، وأعمال إعادة التشغيل. يحافظ ذلك على مواءمة
الملحقات الجانبية المعبأة وسجلات المكونات الإضافية المملوكة للقناة مع
بنية OpenClaw المثبتة، مع ترك إعادة بناء إكمال أوامر المكونات الإضافية الكاملة
لتشغيلات `openclaw completion --write-state` الصريحة.

عند تثبيت خدمة Gateway مُدارة محلية وتمكين إعادة التشغيل،
توقف تحديثات مدير الحزم الخدمة الجارية قبل استبدال شجرة الحزمة،
ثم تنعش بيانات الخدمة الوصفية من التثبيت المحدّث، وتعيد تشغيل
الخدمة، وتتحقق من أن Gateway المعاد تشغيلها تبلغ عن الإصدار المتوقع قبل
الإبلاغ عن النجاح. على macOS، يتحقق فحص ما بعد التحديث أيضًا من أن LaunchAgent
محمّل/قيد التشغيل للملف النشط وأن منفذ local loopback المكوّن
سليم. إذا كان plist مثبتًا لكن launchd لا يشرف عليه، يعيد OpenClaw
تمهيد LaunchAgent تلقائيًا، ثم يعيد تشغيل فحوصات
الصحة/الإصدار/جاهزية القناة. يحمّل التمهيد الجديد مهمة RunAtLoad
مباشرة، لذلك لا يقوم استرداد التحديث فورًا بتشغيل `kickstart -k` على Gateway
الذي أُنشئ حديثًا. إذا ظل Gateway غير سليم، يخرج الأمر
بقيمة غير صفرية ويطبع مسار سجل إعادة التشغيل إضافة إلى تعليمات صريحة لإعادة التشغيل
وإعادة التثبيت والتراجع عن الحزمة. مع `--no-restart`،
يظل استبدال الحزمة يعمل، لكن الخدمة المُدارة لا تُوقف أو
تُعاد تشغيلها، لذلك قد يستمر Gateway الجاري في استخدام الشفرة القديمة إلى أن تعيد تشغيله
يدويًا.

## تدفق نسخة git

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

- `stable`: يسحب أحدث وسم غير beta، ثم يبني ويشغّل doctor.
- `beta`: يفضّل أحدث وسم `-beta`، لكنه يرجع إلى أحدث وسم stable عندما تكون beta مفقودة أو أقدم.
- `dev`: يسحب `main`، ثم يجلب ويعيد الأساس.

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

<Steps>
  <Step title="التحقق من نظافة شجرة العمل">
    يتطلب عدم وجود تغييرات غير ملتزم بها.
  </Step>
  <Step title="تبديل القناة">
    يبدّل إلى القناة المحددة (وسم أو فرع).
  </Step>
  <Step title="جلب المنبع">
    خاص بـ Dev فقط.
  </Step>
  <Step title="بناء تمهيدي (خاص بـ dev فقط)">
    يشغّل بناء TypeScript في شجرة عمل مؤقتة. إذا فشل الطرف، يرجع حتى 10 التزامات للعثور على أحدث التزام قابل للبناء. اضبط `OPENCLAW_UPDATE_PREFLIGHT_LINT=1` لتشغيل lint أيضًا أثناء هذا الفحص التمهيدي؛ يعمل lint في وضع تسلسلي مقيد لأن مضيفات تحديث المستخدم غالبًا أصغر من مشغلات CI.
  </Step>
  <Step title="إعادة الأساس">
    يعيد الأساس إلى الالتزام المحدد (خاص بـ dev فقط).
  </Step>
  <Step title="تثبيت التبعيات">
    يستخدم مدير حزم المستودع. بالنسبة إلى نسخ pnpm، يمهّد المحدّث `pnpm` عند الطلب (عبر `corepack` أولًا، ثم رجوع مؤقت إلى `npm install pnpm@11`) بدلًا من تشغيل `npm run build` داخل مساحة عمل pnpm.
  </Step>
  <Step title="بناء واجهة التحكم">
    يبني gateway وواجهة التحكم.
  </Step>
  <Step title="تشغيل doctor">
    يعمل `openclaw doctor` كفحص التحديث الآمن النهائي.
  </Step>
  <Step title="مزامنة المكونات الإضافية">
    يزامن المكونات الإضافية إلى القناة النشطة. يستخدم Dev المكونات الإضافية المضمنة؛ وتستخدم stable وbeta ‏npm. يحدّث تثبيتات المكونات الإضافية المتتبعة.
  </Step>
</Steps>

على قناة تحديث beta، تحاول تثبيتات مكونات npm وClawHub الإضافية المتتبعة التي تتبع
خط default/latest إصدار المكوّن الإضافي `@beta` أولًا. إذا لم يكن للمكوّن الإضافي
إصدار beta، يرجع OpenClaw إلى مواصفة default/latest المسجلة ويبلغ
عن ذلك كتحذير. بالنسبة إلى مكونات npm الإضافية، يرجع OpenClaw أيضًا عندما تكون حزمة beta
موجودة لكنها تفشل في تحقق التثبيت. لا تجعل تحذيرات الرجوع الخاصة بالمكونات الإضافية هذه
تحديث النواة يفشل. لا تُعاد كتابة الإصدارات الدقيقة والوسوم الصريحة.

<Warning>
إذا حُل تحديث مكوّن npm إضافي مثبت بدقة إلى أثر تختلف سلامته عن سجل التثبيت المخزن، فإن `openclaw update` يوقف تحديث أثر ذلك المكوّن الإضافي بدلًا من تثبيته. أعد تثبيت المكوّن الإضافي أو حدّثه صراحة فقط بعد التحقق من أنك تثق بالأثر الجديد.
</Warning>

<Note>
تُبلغ إخفاقات مزامنة المكونات الإضافية بعد التحديث، عندما تكون محددة ضمن مكوّن إضافي مُدار ويمكن لمسار المزامنة الالتفاف حولها (مثل سجل npm لا يمكن الوصول إليه لمكوّن إضافي غير أساسي)، كتحذيرات بعد نجاح تحديث النواة. تحتفظ نتيجة JSON بالحالة العليا للتحديث `status: "ok"` وتبلغ عن `postUpdate.plugins.status: "warning"` مع إرشادات `openclaw doctor --fix` و`openclaw plugins inspect <id> --runtime --json`. لا تزال استثناءات المحدّث أو المزامنة غير المتوقعة تفشل نتيجة التحديث. أصلح تثبيت المكوّن الإضافي أو خطأ التحديث، ثم أعد تشغيل `openclaw doctor --fix` أو `openclaw update`.

بعد خطوة المزامنة لكل مكوّن إضافي، يشغّل `openclaw update` تمريرة **تقارب ما بعد النواة** إلزامية قبل إعادة تشغيل gateway: يصلح حمولات المكونات الإضافية المكوّنة المفقودة، ويتحقق من كل سجل تثبيت متتبع _نشط_ على القرص، ويتحقق ثابتًا من أن `package.json` الخاص به قابل للتحليل (وأن أي `main` مُعلَن صراحة موجود). تعيد الإخفاقات من هذه التمريرة — ولقطة إعدادات OpenClaw غير الصالحة — القيمة `postUpdate.plugins.status: "error"` وتقلب حالة التحديث العليا إلى `"error"`، لذلك يخرج `openclaw update` بقيمة غير صفرية ولا يُعاد تشغيل gateway بمجموعة مكونات إضافية غير متحقق منها. يتضمن الخطأ أسطر `postUpdate.plugins.warnings[].guidance` منظمة تشير إلى `openclaw doctor --fix` و`openclaw plugins inspect <id> --runtime --json` للمتابعة. تُتخطى إدخالات المكونات الإضافية المعطلة والسجلات غير المرتبطة بمصادر موثوقة كأهداف مزامنة رسمية هنا، بما يعكس سياسة `skipDisabledPlugins` المستخدمة في فحص الحمولات المفقودة، لذلك لا يمكن لسجل مكوّن إضافي معطل قديم أن يمنع تحديثًا صالحًا otherwise.

عند بدء Gateway المحدّث، يكون تحميل المكونات الإضافية للتحقق فقط: لا يشغّل بدء التشغيل مديري الحزم ولا يغيّر أشجار التبعيات. تتجاوز عمليات إعادة التشغيل الخاصة بمدير الحزم `update.run` التأجيل الخامل العادي وفترة تهدئة إعادة التشغيل بعد تبديل شجرة الحزمة، لذلك لا يمكن للعملية القديمة أن تواصل تحميل الأجزاء المحذوفة بكسل عند الحاجة.

إذا ظل تمهيد pnpm يفشل، يتوقف المحدّث مبكرًا مع خطأ خاص بمدير الحزم بدلًا من محاولة `npm run build` داخل نسخة المصدر.
</Note>

## الاختصار `--update`

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

## ذات صلة

- `openclaw doctor` (يعرض تشغيل التحديث أولًا على نسخ git)
- [قنوات التطوير](/ar/install/development-channels)
- [التحديث](/ar/install/updating)
- [مرجع CLI](/ar/cli)