Skip to content

ماذا تفعل إذا فشل التثبيت أو لم يعمل: استكشاف أخطاء التثبيت والإقلاع وإصلاحها ​

OpenClaw فشل التثبيت أو عدم العمل يعود غالبًا إلى ثلاث نقاط: بيئة Node لا تستوفي الحد الأدنى، وCLI غير موجود في PATH، وتعذر إقلاع Gateway بسبب التهيئة. هذه الصفحة تأخذ الأخطاء الشائعة من وثائق استكشاف الأخطاء الرسمية وتقدم لكل منها السبب والحل حسب «النص الأصلي للخطأ» — ابدأ بالفحص السريع في 60 ثانية، ثم طابق الخطأ مع القسم المناسب. النصوص الأصلية للأخطاء مأخوذة بالكامل من الوثائق الرسمية ومخرجات تشخيص CLI، بناءً على v2026.10.9.

ماذا ستستطيع أن تفعل بعد التعلم ​

  • تحديد الطبقة التي بها المشكلة — البيئة، أو CLI، أو Gateway، أو التهيئة — باستخدام 5 أوامر تشخيص رسمية خلال 60 ثانية
  • مطابقة 21 خطأً شائعًا مع القسم المناسب: النص الأصلي للخطأ ← السبب ← أمر الإصلاح
  • التمييز بين حدود استكشاف الأخطاء في الطبقات الأربع: البيئة ← عملية Gateway ← التهيئة والمصادقة ← اتصال العميل
  • معرفة الأوامر الثلاثة الأولى التي يجب تشغيلها للاستعادة بعد فشل التحديث، وأين تطلب المساعدة
  • استخدام openclaw doctor وopenclaw triage الأداتين الرسميتين لإجراء فحص شامل وتشخيص منزوع الحساسية

مأزقك الحالي ​

  • انتهى تثبيت npm، وبمجرد كتابة openclaw تظهر command not found؛ وعند التثبيت بـ sudo يظهر خطأ صلاحيات
  • تم تثبيت Gateway بصعوبة، وبفحص openclaw gateway status يظهر أنه stopped، والسجل يمتلئ بسلسلة من الأخطاء غير المألوفة
  • بعد التحديث لا يعمل أصلًا: القنوات فارغة، واستدعاء النموذج يعيد 401، ولا تعرف هل أفسد التحديث الأمر أم أنك أفسدت التهيئة بنفسك

متى تستخدم هذه الطريقة ​

عندما تحتاج إلى:

كما أنك لا تريد:

  • الذهاب إلى المنتدى ونشر موضوع والانتظار عند كل خطأ — الفحص السريع في 60 ثانية يوفر معظم الانتظار
  • عدم التمييز بين «البيئة معطوبة» و«التهيئة معطوبة»، فتغيّر في الجهتين عشوائيًا

🎒 التحضير قبل البدء ​

  • اجتزت التثبيت عبر المسار الرئيسي أو طرق التثبيت البديلة — لا يهم في أي خطوة علِقت، فهذه الصفحة مخصصة لحل التعطل
  • الطرفية قادرة على تشغيل الأوامر: في macOS / Linux / WSL2 استخدم Bash، وفي Windows استخدم PowerShell
  • عادة نسخ النص الأصلي للخطأ كاملًا — هذه الصفحة مجمّعة حسب النص الأصلي للخطأ، والنسخ الحرفي يسهّل المطابقة

الفكرة الأساسية ​

حدّد الطبقة أولًا، ثم اقرأ الخطأ. من كتابة الأمر إلى استلام رد الذكاء الاصطناعي تمر بأربع طبقات، وأخطاء كل طبقة تبدو مختلفة:

الطبقةما الذي يحدثفحص سريعخطأ نموذجي
1. البيئةNode قديم جدًا أو غير مثبت؛ CLI ليس في PATHnode -v / openclaw --versioncommand not found، node:sqlite truncates TEXT
2. عملية Gatewayلا تقلع، أو المنفذ مشغول، أو الخدمة المثبتة لا تعملopenclaw gateway statusEADDRINUSE، Gateway start blocked
3. الإعداد والمصادقةملف الإعداد تالف أو الرمز (token) غير صحيحopenclaw doctorInvalid config at ... وAUTH_TOKEN_MISSING
4. اتصال العميللا يستطيع Control UI الاتصالcurl http://127.0.0.1:18789gateway connect failed:

أيسر الطريق هو أداتا التشخيص الرسميتان. openclaw doctor يفحص الحالة ويصلح مشاكل الإعداد/الخدمات الشائعة؛openclaw triage يُنشئ تقرير تشخيص منزوع الحساسية (لا يتضمن secrets أو token أو محتوى المحادثات الأصلي أو السجلات الأصلية)، يمكنك تسليمه مباشرة لوكيل برمجي على جهازك ليكمل الإصلاح؛ وإذا لم تجب Yes خلال 30 ثانية عند ظهور رسالة التأكيد، فسيتم تخطي التشغيل وطباعة ذلك الأمر اليدوي فقط.

💡 الشبكة المحلية (الصينية)

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

الفحص الأول: فحص سريع في 60 ثانية ​

شغّل الأوامر الخمسة بالترتيب، للتحقق تباعًا من Node وCLI وGateway والإعدادات، وأي أمر يفشل ابدأ الإصلاح من تلك الطبقة.

bash
# 1. Node 在支持范围吗?——要 24.16.0+(24.x)或 26.1.0+,建议 24.22.1+/26.12.1+
node -v

# 2. CLI 装上了吗?——应打印版本号(本页基准 v2026.10.9)
openclaw --version

# 3. Gateway 起来了吗?——应看到 Runtime: running、监听 18789
openclaw gateway status

# 4. 配置/服务有内伤吗?——应无 blocking 错误
openclaw doctor

# 5. 还是一头雾水?——一键生成脱敏诊断
openclaw triage

المفترض أن ترى: الأمر رقم 1 يطبع v24.16.0+ أو v26.1.0+؛ والأمر رقم 2 يطبع رقم الإصدار؛ والأمر رقم 3 Runtime: running؛ والأمر رقم 4 بلا أخطاء معيقة. أي أمر يفشل، انتقل إلى المجموعة المقابلة أدناه.

استكشاف المشاكل الشائعة ​

التثبيت والبيئة: التثبيت لا ينجح ​

"openclaw: command not found" ​

السبب: نص الوثائق الرسمية حرفيًا «تقريبًا دائمًا مشكلة PATH» — دليل bin العام الخاص بـ npm ليس ضمن PATH في الـ shell لديك. وإذا كنت تستخدم مدير إصدارات مثل nvm / fnm دون إضافته إلى ملف بدء الـ shell، فستواجه المشكلة نفسها. أما الصيغة على Windows فهي openclaw is not recognized.

الحل:

  1. ثلاثة أسطر لتحديد الموقع:
bash
node -v           # Node 装了吗
npm prefix -g     # 全局包装在哪
echo "$PATH"      # 全局 bin 目录在 PATH 里吗
  1. macOS / Linux: أضف دليل bin العام إلى PATH واكتبه في ملف بدء الـ shell (في zsh هو ${ZDOTDIR:-$HOME}/.zshrc، وفي bash هو ~/.bashrc):
bash
export PATH="$(npm prefix -g)/bin:$PATH"

ثم افتح طرفية جديدة، أو نفّذ rehash في zsh، وhash -r في bash.

  1. Windows: أضف دليل المخرجات لـ npm config get prefix (في معظم الأنظمة %AppData%\npm، دون إضافة لاحقة \bin) إلى PATH الخاص بالمستخدم، ثم أعد فتح PowerShell.

المفترض أن ترى: في الطرفية الجديدة يطبع openclaw --version رقم الإصدار.

"npm error spawn git / git not found" ​

السبب: مثبّت Windows لا يجد Git عند سلوك مسار تثبيت git — إما أن Git for Windows غير مثبت، أو مثبت لكنه ليس في PATH.

الحل: ثبّت Git for Windows (كما توصي الأسئلة الشائعة الرسمية)، وتأكد أن git في PATH ← أغلق PowerShell تمامًا وأعد فتحه ← أعد تشغيل المثبّت.

"EACCES" (رفض صلاحية npm install -g) ​

السبب: على Linux يُنسب دليل npm العام إلى root، والمستخدم الحالي لا يستطيع الكتابة فيه.

الحل: غيّر بادئة npm العامة إلى دليل قابل للكتابة من المستخدم:

bash
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"

اكتب سطر export PATH=... في ~/.bashrc أو ${ZDOTDIR:-$HOME}/.zshrc، ثم أعد تثبيت OpenClaw.

"blocked because they are not covered by allowScripts" ​

السبب: npm 12 يعترض افتراضيًا سكربتات دورة حياة الحزم غير المعتمدة، فيُحجب preinstall / postinstall الخاص بـ OpenClaw. أما npm 11.16 فيحذّر فقط لكنه يسمح بالتنفيذ؛ وnpm 11.15 وما قبله لا يطبّق هذه السياسة. انتبه للمطبّ: الأمر npm approve-scripts openclaw الذي يقترحه npm 11.16 لا يعمل مع التثبيت العام — سيرجع ENOMATCH No installed packages match: openclaw.

الحل: مرّر المعامل الصحيح أثناء التثبيت:

bash
# npm 12 或 11.16+
npm install -g openclaw@latest --allow-scripts=openclaw
# npm 11.15 及更早:同命令去掉 --allow-scripts=openclaw

Node <v>: node:sqlite truncates TEXT at embedded NUL (nodejs/node#61954); use 24.16+/26.1+ or a build with the fix ​

السبب: الحد الأدنى الصارم لـ OpenClaw: Node 24.16.0+ (‏24.x) أو 26.1.0+ (تعبير engines هو >=24.16.0 <25 || >=26.1.0)، وأن تجتاز مكتبة SQLite المحمّلة تحقق أمان WAL (SQLite 3.51.3+، أو في 3.50.x ما ≥ 3.50.7، وفي 3.44.x ما ≥ 3.44.6). أما Node 22 و23 و25 فغير مدعومة إطلاقًا؛ وتوصي الجهة الرسمية بشدة بـ 24.22.1+ / 26.12.1+ (إصلاحات أمنية).

الحل:

  1. تحقق من الإصدار بـ node -v، وإن كان قديمًا جدًا فقم بالترقية (‏Node 26 هو الإصدار الموصى به). في الطرفية التفاعلية سيقترح CLI ‏Update NodeJS: Y/N [N]: — اضغط Y لتنزيل وقت تشغيل خاص مُتحقق منه إلى ~/.openclaw/tools/cli-node دون المساس بـ Node النظامية.
  2. إذا افتقد المثبّت الرسمي Node فسيضيفها تلقائيًا: على macOS يثبّت Node 26، وعلى Linux يثبّت Node 24 LTS.
  3. حدود المنصات: ثنائيات macOS الرسمية لـ Node 24+ مبنية على macOS 13.5+، و11–13.4 غير مختبر وغير مدعوم؛ وLinux ARMv7 لا تتوفر لها بنية رسمية، فيجب استخدام نظام 64 بت.
  4. توزيعات RPM (Fedora / RHEL): تربط Node الخاصة بالتوزيعة بـ SQLite نظامي غير آمن، فيحوّل المثبّت الرسمي تلقائيًا إلى وقت تشغيل في وضع المستخدم دون تدخل منك.

المفترض أن ترى: يطبع node -v v24.16.0+ أو v26.1.0+ وتختفي الأخطاء. وتذكّر الجهة الرسمية أيضًا: قم بترقية Node أولًا قبل تحديث OpenClaw، تجنبًا لاقتطاع TEXT في SQLite.

"blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)" ​

السبب: صورة Docker تعمل بالمستخدم node (uid 1000)، ومالك الدليل المُركّب على المضيف لا يطابقه، فتحجب سياسة الأمن الإضافة، وغالبًا تتبعها رسالة plugin present but blocked.

الحل: غيّر مالك الدليل المُركّب إلى 1000:

bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fix

فقط إذا كنت تشغّل OpenClaw بـ root على المدى الطويل غيّر /path/to/openclaw-config/npm إلى root:root. لتفاصيل النشر عبر Docker انظر نشر الخادم.

💡 المثبّت عالق بلا أي استجابة؟

أعد تشغيله مع إضافة --verbose:

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

install.ps1 لا يحتوي على مفتاح تبديل مقابل؛ غلِّفه بطبقة باستخدام Set-PSDebug -Trace 1 / -Trace 0.

Gateway: لا يعمل ​

شغّل أولاً openclaw gateway status (أضف --deep لفحص خدمات النظام معها) و openclaw logs --follow لعرض السجلات، ثم قارن برسائل الخطأ أدناه.

"Gateway start blocked: set gateway.mode=local" ​

السبب: يفتقد التكوين علامة الوضع المحلي لـ gateway.mode — إما أن الوضع المحلي غير مفعّل، أو أن ملف التكوين أُفسد وفقد الحقل (قد تكتب السجلات أيضًا existing config is missing gateway.mode). عند النشر عبر Podman انتبه إلى أن مسار التكوين الافتراضي هو ~/.openclaw/openclaw.json.

الحل (طريقتان رسميتان):

  1. عيّن gateway.mode="local" في التكوين؛
  2. أو أعد تشغيل openclaw onboard --mode local / openclaw setup لإعادة توليد تكوين الوضع المحلي.

"another gateway instance is already listening" / EADDRINUSE ​

السبب: المنفذ الافتراضي 18789 مشغول — غالبًا بسبب تثبيت خدمة Gateway مكررة، أو عملية أخرى احتلت المنفذ.

الحل:

  1. استخدم openclaw gateway status --deep لفحص خدمات launchd / systemd / المهام المجدولة المكررة، وانتبه لتلميح التنظيف Other gateway-like services detected (best effort).
  2. توصي الجهة الرسمية بتثبيت Gateway واحد لكل جهاز في معظم الحالات؛ وإذا كنت تحتاج فعلاً إلى تشغيل أكثر من واحد، فيجب عزل المنافذ + الإعدادات + الحالة + مساحة العمل.
  3. حالة خاصة على macOS: نشاط LaunchAgent بالاسمين ai.openclaw.gateway و ai.openclaw.node في وقت واحد يسبب حلقة سريعة من EADDRINUSE/respawn — إذا لم تكن بحاجة إلى وظيفة node فنفّذ openclaw node uninstall.
  4. بعد اكتمال تنظيف openclaw gateway restart، يجب أن يعرض status Runtime: running.

"refusing to bind gateway ... without auth" ​

السبب: يستمع Gateway افتراضيًا فقط إلى عنوان الاسترجاع المحلي (loopback) + المنفذ 18789. تريد الربط بعنوان غير loopback دون تكوين مصادقة — OpenClaw يرفض الإقلاع (fail closed، وهذا تصميم أمني مقصود).

الحل: أحد خيارين:

  1. الاستمرار في الاستماع إلى loopback فقط، مع وصول بعيد عبر نفق SSH (ssh -N -L 18789:127.0.0.1:18789 user@gateway-host) أو Tailscale؛
  2. تكوين مصادقة لـ Gateway (token / password، أو trusted-proxy)، والقواعد في تقوية الأمان (1). لم تضبط shared secret بعد؟ openclaw doctor --generate-gateway-token لتوليد واحد.

"Invalid config at ..." ​

السبب: ملف التكوين لم يجتز التحقق — تعديل يدوي أفسده، أو بنيته خاطئة، أو دخلت مفاتيح غير معروفة. يرفض Gateway الإقلاع؛ كما أن Gateway قيد التشغيل يتخطى التعديلات الفاسدة عند إعادة التحميل الساخن (تكتب السجلات config reload skipped (invalid config): ...).

الحل:

  1. التحديد والتحقق:
bash
openclaw config file       # 配置文件在哪
openclaw config validate   # 哪一条不过
  1. دع doctor يصلح: openclaw doctor --fix يمكنه إصلاح التكوين الفاسد أو استعادة آخر نسخة صالحة معروفة؛ يُحتفظ بالمحتوى الفاسد المرفوض في ملفات .rejected.* / .clobbered.* المجاورة (.clobbered.* يحتفظ بأحدث 32 نسخة لكل مسار تكوين)، فإذا أردت استعادة مفاتيح عدلتها فقط فانسخها من هناك.
  2. عند الإصلاح اليدوي: حافظ على بنية JSON5 الكاملة، وعدّل المفتاح المستهدف فقط، وبعد التعديل اجتز openclaw config validate ثم أعد التشغيل.

"Gateway service port does not match current gateway config" ​

السبب: خدمة الخلفية المثبتة ما زالت تحمل --port القديم — يحدث غالبًا بعد تعديل تكوين المنفذ.

الحل:

bash
openclaw doctor --fix      # 或 openclaw gateway install --force
openclaw gateway restart

Control UI: لا يمكن الاتصال ​

Gateway يعمل لكن المتصفح لا يتصل؟ أخطاء هذه المجموعة تقع جميعها في الجزء الأخير من مسار «العميل → Gateway».

"gateway connect failed:" ​

السبب: عنوان URL / المنفذ الذي يشير إليه Control UI خاطئ، أو أن Gateway لا يعمل أصلًا.

الحل: تحقق ثلاثي على الجهاز المحلي:

bash
openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789

curl يسحب HTML الخاص بـ OpenClaw → Gateway سليم والمشكلة في جانب المتصفح: افتح http://127.0.0.1:18789 مباشرة، وامسح ذاكرة التخزين المؤقت، ولا تستخدم روابط عميقة قديمة. إذا لم تنهض الخدمة بعد restart، فنفّذ openclaw gateway start ثم تحقق عبر openclaw gateway status.

"AUTH_TOKEN_MISSING" ​

السبب: مكوَّن Gateway بمصادقة token / password، لكن العميل لم يرسل shared token.

الحل:

  1. احصل على token من الطرفية التفاعلية على مضيف Gateway:
bash
openclaw gateway auth-token --show
  1. الصق المخرجات في إعدادات Control UI وأعد المحاولة. لم تضبط token بعد؟ openclaw doctor --generate-gateway-token لتوليده؛ ومصدر token هو gateway.auth.token (أو متغير البيئة OPENCLAW_GATEWAY_TOKEN).
  2. إذا استمر فشل الاتصال، فقارن بجدول رموز أخطاء auth الرسمي:
رمز الخطأالمعنىالخطوة التالية
AUTH_TOKEN_MISMATCHعدم تطابق shared tokenاسمح بإعادة محاولة موثوقة واحدة بـ device token؛ عند استمرار الفشل اتبع قائمة انزياح token الرسمية
AUTH_DEVICE_TOKEN_MISMATCHdevice token قديم جدًا أو ملغىبدّل/أعد الموافقة عبر devices CLI
AUTH_SCOPE_MISMATCHصلاحيات device token غير كافيةأعد الاقتران أو وافق على scope المطلوب، ولا تلجأ إلى تدوير shared token
PAIRING_REQUIREDهوية الجهاز بانتظار الموافقةopenclaw devices approve <requestId>

"device identity required" و "origin not allowed" ​

السبب: الأول — العميل لم يرسل هوية الجهاز (لا يمكن حذفها حتى في وضع token / password، وshared secret لا يحل محلها)؛ الثاني — Origin الخاص بالمتصفح ليس في القائمة البيضاء، والنشر على الشبكة العامة أو عبر المصادر يتطلب إضافة مدخل في gateway.controlUi.allowedOrigins (الشبكة المحلية الخاصة وعناوين Tailscale لا تحتاج قائمة بيضاء).

الحل: الأول أعد إتمام اقتران الجهاز؛ الثاني أضف Origin الخاص بالنشر إلى gateway.controlUi.allowedOrigins ثم أعد الاتصال.

"too many failed authentication attempts (retry later)" ​

السبب: Origin نفس المتصفح فشل في المصادقة مرارًا، فأُقفل مؤقتًا. أصول localhost الأخرى لها حاويات عدّ مستقلة ولا تتأثر.

الحل: توقف عن مواصلة الاصطدام بالقفل؛ تأكد أولًا وفق بند AUTH_TOKEN_MISSING من صحة بيانات الاعتماد، ثم أعد المحاولة لاحقًا.

يعلق عند "Wake up, my friend!" دون رد ​

السبب: شاشة الحضانة في onboarding تعتمد على إمكانية الوصول إلى Gateway وأن المصادقة قد تمت. إذا تم تخطي إعداد النموذج / المصادقة، سينبهك المعالج برسالة Model auth missing ويفتح TUI مباشرة دون إرسال رسائل؛ وإذا رأيت عبارة الاستيقاظ لكن توقفت الـ tokens عند 0، فهذا يعني أن الـ agent لم يعمل أصلًا.

الحل:

bash
openclaw gateway restart
openclaw status
openclaw models status
openclaw logs --follow

إن لم ينجح ذلك فجرّب openclaw doctor. إذا لم يكن مزوّد النموذج أو بيانات الاعتماد مُهيّأين بشكل صحيح، فشغّل openclaw onboard لإعادة الإعداد — هذا هو الأمر الرسمي الوحيد المخصص لـ «تغيير مزوّد النموذج والمصادقة».

فشل التحديث ​

مداخل الاسترداد بعد فشل التحديث ثلاثة ثابتة: openclaw update status --json (لاطّلاع على خطوة الفشل المسجّلة ورمز السبب)، وopenclaw triage (تشخيص منزوع الحساسية)، وopenclaw doctor --fix. في Settings → Updates ضمن Control UI يمكنك رؤية وقت آخر محاولة، والإصدارين قبل وبعد، وخطوة الفشل، ورمز السبب (reason code).

"managed-service-handoff-failed" ​

السبب: عندما يكون مستوى سجلات console هو debug، يُرفض تسليم التحديث في الإصدارات المتأثرة. إصدارات stable المتأثرة: 2026.9.6–2026.9.9 و2026.10.1–2026.10.5.

الحل: اضبط logging.consoleLevel على "info"، وأزل OPENCLAW_LOG_LEVEL=debug من بيئة Gateway وأوامر التحديث (يمكن لسجلات الملف البقاء debug)، ثم شغّل openclaw update، وبعد الانتهاء استعد إعدادات السجل الأصلية.

"global-install-permission-denied" ​

السبب: بادئة npm العامة غير قابلة للكتابة — يحدث هذا غالبًا مع Node المثبّت عبر Homebrew، أو بادئة النظام، أو بعد التبديل بين مديري الإصدارات فأصبحت الإشارة إلى بادئة أخرى.

الحل: راجع الدليل والمالك المذكورين في رسالة الخطأ:

  1. إذا كان الدليل ملكك → اتبع أمر chmod u+rwx المذكور في رسالة الخطأ للإصلاح؛
  2. إذا كان الدليل ملك المسؤول → اطلب من حساب لديه الصلاحية تنفيذ التحديث، أو اطلب منحك الصلاحية؛
  3. في التثبيت الشخصي يمكنك التحويل إلى بادئة قابلة للكتابة من المستخدم (راجع حيلة EACCES أعلاه).

::: تحذير ⚠️ لا تستخدم sudo لتشغيل أداة التحديث بأكملها التحذير الرسمي واضح: تشغيل أداة التحديث بأكملها باستخدام sudo قد يختار home وحساب خدمة مختلفين. ولا تغيّر ملكية بادئة النظام المشتركة بشكل تكراري أيضًا. :::

"ETARGET" / "E404" / "EINTEGRITY" ​

السبب: فشل npm في تحليل الحزمة أو تنزيلها — الإصدار الهدف غير موجود في الـ registry، أو ذاكرة التخزين المؤقت قديمة، أو هناك مشكلة في إعدادات الـ registry / المرآة.

الحل:

bash
npm cache verify
npm view <spec> version   # 用报错里给出的 spec 验证

تحقق من الـ registry أو المرآة التي هيأتها ثم أعد المحاولة. تعيد أداة التحديث الحالية المحاولة تلقائيًا مرة واحدة عند فشل تبعية مسمّاة (npm يستخدم --prefer-online، وBun يستخدم --no-cache).

"protocol mismatch" (يتكرر باستمرار بعد التراجع) ​

السبب: بعد التراجع إلى إصدار قديم من Gateway، ما تزال هناك عمليات عميل أحدث تعيد الاتصال باستخدام نطاق بروتوكول لا يفهمه الـ Gateway القديم. تبدو السجلات مثل protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>.

الحل:

  1. استخدم openclaw gateway status --deep (أو openclaw doctor --deep) للعثور على PID العميل القديم (stale) وأوقفه؛
  2. أعد تشغيل الأشياء التي تتضمن OpenClaw: لوحة التحكم المحلية، والمحرر، وhelper الخاص بـ app-server، والـ shell طويلة الأمد التي تشغّل openclaw logs --follow؛
  3. ثم شغّل --deep مرة أخرى للتأكد من اختفاء الـ PID القديم. لا تجعل الـ Gateway القديم يقبل البروتوكول الجديد بالقوة — إصدار البروتوكول موجود لحماية عقد الاتصال.

"plugin load failed: dependency tree corrupted; run openclaw doctor --fix" ​

السبب: بعد اكتمال التحديث مباشرة، تكون قائمة القنوات فارغة أو ترجع استدعاءات النموذج الخطأ 401 — كلاهما يشير إلى أن خطوات التحديث الختامية لم تكتمل: فشل تسجيل إضافة القناة (إعداد القناة ما زال موجودًا لكن الإضافة لم تُحمَّل)؛ أو خطأ 401 من المزوّد ناتج عن ظل قديم لبيانات اعتماد OAuth لكل agent.

الحل: سلسلة الاسترداد العامة الخمسية بعد التحديث:

bash
openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

doctor --fix ينظّف ظلال OAuth القديمة ويصلح شجرة التبعيات التالفة. كما تذكّر الوثائق الرسمية: بعد فشل التحديث لا تتراجع عن الحالة فورًا — احتفظ أولًا بالحالة الحالية وأعد تثبيت كود معروف بجودته، ولا تستعد النسخة الاحتياطية التي سبقت التحديث إلا عندما يعجز الكود القديم عن قراءة الإعدادات / قاعدة البيانات الجديدة.

لم ينجح بعد؟ ​

اجمع الأدلة أولًا قبل طرح السؤال. جدول أوامر التشخيص في دليل «I am stuck» الرسمي — شغّله بالكامل وأرفق المخرجات (بعد إزالة الحساسية):

الأمرما الذي يمكنك رؤيته
openclaw statusحالة Gateway / agent + لقطة للإعدادات الأساسية
openclaw status --allتشخيص كامل للقراءة فقط، يمكن لصقه مباشرة
openclaw models statusمصادقة المزوّد + توفر النموذج
openclaw doctorالتحقق من مشاكل الإعدادات / الحالة الشائعة وإصلاحها
openclaw logs --followذيل السجلات المباشرة
openclaw gateway status --deepفحص عميق لـ Gateway / الإعدادات / الإضافات
openclaw health --verboseتقرير صحة مفصّل

في حالات فشل التحديث أرفق أيضًا مخرجات openclaw update status --json. أمر openclaw triage واحد يكفي لتوليد تشخيص منزوع الحساسية — راجعه قبل الإرسال، ولا ترفق بيانات اعتماد أو إعدادات خام أو مخرجات عمليات غير منزوعة الحساسية.

إلى أين تتوجه بالسؤال:

القناةما المناسب لها
community.openclaw.aiموقع الدعم الرسمي: ابدأ هنا لمشاكل الإعدادات والبيئة
GitHub issue chooserعيوب المنتج القابلة لإعادة الإنتاج / أخطاء التوثيق، مع خطوات إعادة الإنتاج والأدلة
وثائق استكشاف الأخطاء الرسميةالمدخل الرسمي لاستكشاف الأخطاء المرتّب حسب الأعراض، ومصدر العديد من الأخطاء المذكورة في هذه الصفحة

نقاط التحقق ✅ ​

  • 60 ثانية: فحص سريع لتشغيل الأوامر الخمسة ومعرفة الطبقة التي علِقت فيها
  • openclaw --version يطبع رقم الإصدار، وتم إصلاح command not found
  • node -v ضمن النطاق 24.16.0+ (24.x) أو 26.1.0+
  • openclaw gateway status يعرض Runtime: running ويستمع على 18789
  • عند السؤال سأرفق مخرجات تشخيص منزوعة الحساسية مثل openclaw status --all

الأسئلة الشائعة ​

OpenClaw ما معناه؟ ​

OpenClaw هو أداة ذكاء اصطناعي تُثبَّت عبر npm، وتتكون من openclaw CLI وخدمة Gateway الدائمة وواجهة التحكم Control UI في المتصفح، وتُستخدم للاتصال بمزوّدي النماذج المختلفين لتشغيل وكلاء الذكاء الاصطناعي. هذه الصفحة مخصصة لمعالجة أخطاء مرحلتي التثبيت والتشغيل؛ إذا فشل التثبيت أو لم يعمل، راجع أولاً «فحص 60 ثانية» أعلاه.

OpenClaw كيف يُستخدم؟ هل يوجد شرح تفصيلي؟ ​

تبدأ التجربة من التثبيت: اتبع أولاً التثبيت: جاهز خلال 5 دقائق، أو اختر طرق التثبيت البديلة. بعد التثبيت استخدم openclaw gateway status للتحقق من Runtime: running والاستماع على 18789، ثم استخدم openclaw onboard لإكمال إعداد النماذج والمصادقة، ثم افتح http://127.0.0.1:18789 في المتصفح لاستخدام Control UI.

خلاصة هذا الدرس ​

✅ في استكشاف الأخطاء حدّد الطبقة أولًا: البيئة (Node / CLI) → عملية Gateway → الإعدادات والمصادقة → اتصال العميل، ولكل طبقة أوامر فحص ثابتة.

✅ الأسباب الرئيسية الثلاثة لفشل تثبيت OpenClaw (مسار PATH، وصلاحيات npm، وإصدار Node) لها حلول ثابتة: إضافة PATH، وتغيير prefix ليكون قابلاً للكتابة من المستخدم، والترقية إلى 24.16.0+/26.1.0+.

✅ تذكّر أداتين رسميتين: openclaw doctor للفحص والإصلاح، وopenclaw triage لإخراج تشخيص منزوع الحساسية يمكن تسليمه مباشرةً إلى وكيل برمجي.

✅ عند فشل التحديث ادخل أولاً من بوابة الاسترداد: openclaw update status --json ← openclaw triage ← openclaw doctor --fix، ولا تتعجل في التراجع عن الحالة.

مرجع سريع لأهم رسائل الأخطاء:

إشارة الخطأالطبقةالخطوة الأولى
openclaw: command not foundالبيئةnpm prefix -g ← إضافة PATH
node:sqlite truncates TEXT ...البيئةترقية Node إلى 24.16+/26.1+
blocked ... allowScriptsالبيئة--allow-scripts=openclaw إعادة التثبيت
Gateway start blocked: set gateway.mode=localGatewayإعادة تعيين gateway.mode=local
EADDRINUSEGatewaystatus --deep البحث عن الخدمات المكررة
Invalid config at ...الإعداداتdoctor --fix + config validate
AUTH_TOKEN_MISSINGالمصادقةgateway auth-token --show
managed-service-handoff-failedالتحديثتعيين consoleLevel إلى info
protocol mismatchالتحديث--deep البحث عن عمليات العميل القديمة وإيقافها

للاطلاع على المرجع الكامل للأوامر والإعدادات، انظر مرجع سريع لأوامر وإعدادات CLI.

استعراض الدرس التالي ​

بعد أن استقرّت البيئة وأصبح Gateway يعمل باستمرار، الخطوة التالية هي توصيل «الدماغ». الدرس التالي: نظرة عامة على ربط النماذج: نظام provider وتبديل النماذج.

ستتعلم:

  • provider/model كيفية قراءة مرجع النموذج، ولماذا لا تحتاج إضافات provider الرسمية إلى كتابة إدخالات في الإعدادات
  • openclaw models عائلة الأوامر: list / set / status
  • المصفوفة الكاملة للنماذج الصينية: DeepSeek وQianwen وGLM وKimi وMiniMax وDoubao... صفحة واحدة لكل مزوّد

دروس ذات صلة ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.