تثبيت OpenClaw وإعداده مع OmniProxy

OpenClaw هو مساعد ذكاء اصطناعي يُثبَّت على جهازك. يمكنك التحدث إليه مباشرة عبر Telegram أو Discord أو WhatsApp أو Feishu من دون إبقاء نافذة دردشة أخرى مفتوحة باستمرار؛ وتظل المحادثات والسجلات على هذا الجهاز، كما يمكنه متابعة تنفيذ الخطوات اللاحقة محليًا.

الاستعداد قبل التثبيت

يتطلب OpenClaw الإصدار Node 24.16 أو أحدث، ويمكن أيضًا استخدام Node 26.1 أو أحدث، ويوصى باستخدام Node 26. تمثل Node البيئة الأساسية اللازمة لتشغيل OpenClaw.

يمكن التثبيت على macOS وLinux وWindows. إذا لم يكن على الجهاز إصدار مناسب من Node، فسيتولى برنامج التثبيت النصي إعداده تلقائيًا: سيُعد Node 26 على macOS وNode 24 LTS على Linux. لا تحتاج إلى pnpm إلا عند بناء OpenClaw من الشيفرة المصدرية.

إذا كان على الجهاز إصدار أقدم من Node، فلا داعي إلى إزالته فورًا. في اختبار 2026-10-09، كان إصدار Node الخاص بالنظام على هذا الجهاز هو 24.2.0، أي أقل من الإصدار المطلوب 24.16، وقد أعد برنامج التثبيت النصي غير التفاعلي إصدار Node 24.21.0 تلقائيًا.

إذا أردت نافذة

مرافق سطح المكتب

• حزمة تثبيت Hub على Windows
• ملف DMG من GitHub على macOS
• يمكن تثبيت Gateway محلي عند التشغيل الأول

الموصى به رسميًا

برنامج التثبيت النصي

• macOS وLinux وWSL2
• استخدم PowerShell على Windows
• يمكن إضافة --no-onboard

إذا كان Node مثبتًا بالفعل

مدير الحزم

• npm أو pnpm أو bun
• ثم شغّل onboard
• راجع صفحة التثبيت لمعرفة إصدار Node

التثبيت والتشغيل لأول مرة

يمكنك تثبيت تطبيق سطح المكتب المرافق ذي الواجهة الرسومية، أو التثبيت مباشرة من الطرفية. Gateway خدمة محلية مسؤولة عن استقبال الرسائل واستدعاء النموذج وإعادة النتائج، ويمكن إعدادها أثناء فتح تطبيق سطح المكتب المرافق لأول مرة.

إذا كنت تريد واجهة رسومية

• Windows: نزّل وشغّل OpenClawCompanion-Setup-x64.exe أو OpenClawCompanion-Setup-arm64.exe. حزمة التثبيت موقّعة، وتتضمن الإعدادات وحالة علبة النظام والدردشة ووضع node.
• macOS: نزّل ملف .dmg الخاص بـ OpenClaw من GitHub releases لـ OpenClaw. يُفضّل استخدام dmg، ويمكن أيضًا استخدام .zip. بعد التثبيت، افتح OpenClaw.app. إذا لم تتضمن هذه النسخة ملفات لنظام macOS، فاتبع ما توضحه صفحة تطبيق macOS.

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

التثبيت باستخدام الطرفية

على macOS وLinux وWSL2 استخدم:

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

على Windows PowerShell استخدم:

iwr -useb https://openclaw.ai/install.ps1 | iex

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

إذا كنت لا تريد بدء المعالج حاليًا، فاستخدم بدلًا من ذلك على macOS وLinux وWSL2:

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

على Windows استخدم الخيار الرسمي -NoOnboard:

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

إذا كنت تدير Node بنفسك، فيمكنك أيضًا استخدام npm أو pnpm أو bun. مع npm 12 وnpm 11.16 أو أحدث، شغّل:

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

يتطلب npm 11.15 والإصدارات الأقدم إزالة --allow-scripts=openclaw. وعند استخدام pnpm يجب إضافة --allow-build=openclaw. راجع صفحة التثبيت لمعرفة الفروق الدقيقة.

بعد اكتمال التثبيت، شغّل الأوامر الثلاثة التالية بالترتيب:

openclaw --version
openclaw doctor
openclaw gateway status

يُستخدم openclaw --version لعرض الإصدار، وopenclaw doctor لفحص مشكلات البيئة الشائعة، وopenclaw gateway status لمعرفة ما إذا كانت Gateway قيد التشغيل. لا يُعد التثبيت الأساسي مكتملًا إلا إذا أظهرت الأوامر الثلاثة مخرجات طبيعية.

إذا أفادت الطرفية بأنها لا تستطيع العثور على openclaw، فعادةً لا يكون مجلد bin العام الخاص بـ npm مضافًا إلى PATH. يمثل PATH قائمة المواقع التي تبحث فيها الطرفية عن البرامج. يمكنك المقارنة باستخدام node -v وnpm prefix -g وecho "$PATH"، ثم إضافة مجلد bin المقابل إلى PATH وإعادة فتح الطرفية.

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

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/openclaw-omniproxy" --no-onboard

يمثل --no-onboard السلوك الافتراضي لهذا البرنامج النصي. في 2026-10-09، ثبّت هذا الأمر OpenClaw 2026.9.9. بعد اكتمال التثبيت، يجب تشغيل openclaw الموجود داخل مجلد bin في ذلك المسار.

الحصول على معلمات الاتصال من OmniProxy

تأكد أولًا من أن OmniProxy قيد التشغيل، ثم افتح قائمة النماذج فيه وجهّز العناصر الثلاثة التالية:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: انسخ المعرّف كاملًا من قائمة نماذج OmniProxy الحالية

baseUrl هو العنوان الذي يرسل إليه OpenClaw طلبات النموذج، ويجب أن ينتهي بـ /v1. عند الاتصال بـ OmniProxy، استخدم openai-completions في الحقل api. لا تغيّره إلى openai-responses إلا إذا كان هذا النموذج يعمل فعلًا عبر /v1/responses.

Model ID هو المعرّف الكامل للنموذج كما يظهر في القائمة. انسخه كما هو، مع الاحتفاظ بأي شرطات مائلة داخله. الاسمان التاليان مجرد مرجعين وردا في وثائق المورّد بتاريخ 2026-10-09؛ لا تستخدمهما إذا لم يكونا موجودين في القائمة: claude-sonnet-5-5 وgpt-6-luna.

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

إدخال إعدادات الأداة

يمكن فهم Provider على أنه مجموعة إعدادات اتصال يستخدمها OpenClaw للعثور على خدمة النموذج. سنسمّي Provider هنا omniproxy.

نفّذ الأمر التالي في الطرفية، واستبدل العنوان والمفتاح ومعرّفي النموذجين بقيمك الخاصة:

openclaw config set models.providers.omniproxy '{"baseUrl":"https://your-omniproxy-origin.example/v1","apiKey":"<YOUR_OMNIPROXY_API_KEY>","api":"openai-completions","models":[{"id":"claude-sonnet-5-5","name":"Claude Sonnet 5.5"},{"id":"gpt-6-luna","name":"GPT-6 Luna"}]}' --strict-json --merge

يكتب هذا الأمر إعدادات Provider وقائمة النماذج في ملف الإعدادات. بعد نجاح الأمر، لا تحتاج إلى إعادة تشغيل Gateway.

بعد ذلك، حدّد النموذج الافتراضي. يتكون مرجع النموذج من omniproxy/ متبوعًا بـ Model ID، مع الاحتفاظ بجميع الشرطات المائلة الموجودة أصلًا في المعرّف. إذا كان المعرّف في قائمة النماذج أطول من الاسم المختصر أدناه، فاستخدم المعرّف الكامل الموجود في القائمة:

openclaw config set agents.defaults.model.primary '"omniproxy/claude-sonnet-5-5"' --strict-json

يمكن عدم كتابة reasoning وinput وcost وcontextWindow وmaxTokens. عند تركها فارغة، ستُعالَج النماذج النصية بالطريقة الافتراضية.

يمكن أيضًا كتابة الإعدادات نفسها مباشرة في ملف الإعدادات. يوجد Provider في الإعدادات الرئيسية ضمن models.providers. ويمكن أن يكون لكل agent ملف models.json خاص به؛ والـ agent هو مثيل المساعد الذي يستقبل المهام فعليًا ويستدعي النموذج. يوجد الملف داخل agent/models.json في مجلد agent المقابل ضمن ~/.openclaw/agents/.

إذا كان ملف models.json هذا يحتوي على قيمة غير فارغة لـ baseUrl، فستتجاوز العنوان الموجود في الإعدادات الرئيسية.

فحص التثبيت

ثلاثة أوامر

• openclaw --version
• openclaw doctor
• gateway status

الإعداد

models.providers

• اجعل baseUrl ينتهي بـ /v1
• استخدم completions في api
• اكتب id للنموذج على الأقل

الاختيار

provider/النموذج

• استخدم هذا المرجع في primary
• يُفضّل استخدام متغير بيئة للمفتاح
• اعتمد قائمة البوابة

التحقق باستخدام مهمة فعلية

انتقل إلى مجلد مشروع عادي وأرسل رسالة قصيرة جدًا. استبدل مرجع النموذج في الأمر بـ Model ID الكامل الخاص بك:

openclaw agent --local --model omniproxy/claude-sonnet-5-5 --timeout 300 --message "أجب بكلمة واحدة."

يعني --local تشغيل مهمة agent هذه محليًا، ويحدد --model النموذج المستخدم في هذه المرة، بينما يعني --timeout 300 الانتظار لمدة أقصاها 300 ثانية.

يجب أن تظهر استجابة فعلية من النموذج في الطرفية. في 2026-10-09، تلقّى OpenClaw 2026.9.9 استجابة باستخدام هذا الأمر. قد يستغرق الاستدعاء الأول دقيقة أو دقيقتين.

إذا ظهر نص الخطأ الأصلي Request timed out before a response was generated، فزِد قيمة --timeout أولًا ثم أرسل الطلب مرة أخرى. يعني ذلك عادةً أن مهلة الانتظار غير كافية، ولا يعني بالضرورة أن العنوان مكتوب بطريقة خاطئة.

بعد نجاح الرد القصير، اطلب منه قراءة ملف محلي تحدده أنت. بعد ذلك، افتح سجلات الاستدعاء في OmniProxy وتأكد من المصدر وModel ID المسجلين. ظهور رقم الإصدار أو مخرجات doctor وحده لا يكفي لإثبات اكتمال إعداد اتصال النموذج.

التثبيت

يستجيب الأمر

• يمكن عرض رقم الإصدار
• لا توجد مشكلة مانعة في doctor
• يمكن قراءة حالة Gateway

المهمة

نفّذ مهمة صغيرة

• مثلًا، قرأ ملفًا محليًا
• الرد ليس رسالة خطأ
• مرجع النموذج مكتوب بصورة صحيحة

السجل

يظهر في البوابة

• المصدر هو OpenClaw
• معرّف النموذج متطابق
• لم يُكتب المفتاح في المستودع

الأخطاء الشائعة

• تعذّر العثور على openclaw: أضف مجلد bin العام الخاص بـ npm إلى PATH، ثم أعد فتح الطرفية. عند التثبيت في مجلد محدد، شغّل البرنامج الموجود في مجلد bin داخله.
• ناتج node -v أقل من 24.16: لا حاجة إلى إزالة الإصدار القديم أولًا. تحقق من إصدار Node الذي أعده برنامج التثبيت النصي، أو استخدم 24.16+ أو 26.1+ وفقًا لصفحة التثبيت. يوصى باستخدام Node 26.
• النموذج لا يظهر: يجب أن يكون النموذج مكتوبًا داخل مصفوفة models في models.providers، ويجب أن يحتوي على الأقل على id مطابق. كتابة agents.defaults.models وحدها لا تسجّل نموذجًا جديدًا بشكل مستقل.
• ظهور الخطأ 400 مع ذكر دور developer: عندما لا يكون مضيف العنوان هو api.openai.com، احتفظ بالإعداد الافتراضي ولا تضبط supportsDeveloperRole على true. حتى إذا ضُبط على true، فستُستبدل قيمته.
• انتهاء المهلة بسرعة: زِد --timeout إلى 300 ثانية أو أكثر، ولا تغيّر العنوان في البداية.
• اختيار gpt-6-luna مع فشل استدعاء الأدوات: يدعم هذا النموذج Chat Completions؛ ولا يُدعم استدعاء الدوال في Chat Completions إلا عندما تكون قيمة reasoning_effort هي none. إذا كان المعرّف في القائمة مختلفًا، فاستخدم المعرّف الموجود في القائمة.
• تعذّر الاتصال بالعنوان: تأكد من أن OmniProxy قيد التشغيل، وأن baseUrl ينتهي بـ /v1، وأن العنوان المكتوب في الإعدادات قابل للوصول. تحتاج عناوين الشبكات الخاصة الأخرى إلى السماح بها بشكل منفصل.
• استمرار الاتصال بعنوان آخر بعد اكتمال الإعداد: تحقق مما إذا كان ملف models.json الخاص بذلك الـ agent يحتوي على baseUrl مختلف.

المراجع الرسمية

راجع OpenClaw install لمعرفة خطوات التثبيت. ولإعداد Provider مخصص، راجع Custom providers وحقول الإعداد. ويمكن مقارنة معرّفات النماذج المستخدمة في المثال مع نظرة عامة على نماذج Claude وGPT-6 Luna.

استبدل كل عنصر نائب بقيم إعداد OmniProxy الخاصة بك. لا تنشر مفتاحاً حقيقياً أبداً.

لا يثبت الحفظ الناجح أو HTTP 200 وحده توافق Agent الكامل. تحقق من المصدر والنموذج في سجل استدعاءات OmniProxy.

المصادر الرسمية · OpenClaw ↗