إذا كنت تحاول تشغيل OpenClaw (الذي يُشار إليه غالبًا في النسخ المجتمعية أو الحزم باسم Moltbot/Clawdbot) محليًا، فإن الجزء الصعب عادةً لا يكون في استنساخ المستودع، بل في التعامل مع إصدارات وقت التشغيل، ومتغيرات البيئة، ومشكلات البناء الخاصة بالمنصة.
يوفر لك هذا الدليل مسار تثبيت عملي ومتعدد المنصات، مع خطوات تصحيح الأخطاء التي تساعد عندما تسوء الأمور.
ما الذي يتضمنه إعداد OpenClaw عادةً
تتبع معظم توزيعات OpenClaw نفس شكل النشر:
- استنساخ الشيفرة المصدرية من Git.
- تثبيت تبعيات اللغة/وقت التشغيل.
- تكوين ملف
.env(الرموز المميزة، قاعدة البيانات، مفاتيح API). - تهيئة التخزين (SQLite/Postgres/Redis حسب البناء).
- تشغيل نصوص الترحيل/التمهيد.
- بدء الخدمة والتحقق من نقاط نهاية الحالة الصحية.
حتى إذا كانت نسختك المحددة تختلف، فإن هذه القائمة المرجعية تنطبق على كل عملية تثبيت تقريبًا.
المتطلبات الأساسية (جميع أنظمة التشغيل)
قبل الخطوات الخاصة بنظام التشغيل، تأكد من هذه الأساسيات:
- Git: لاستنساخ وسحب التحديثات.
- وقت التشغيل: عادةً Node.js (LTS) أو Python (3.10+)، حسب النسخة.
- مدير الحزم: npm/pnpm/yarn لـ Node، pip/poetry لـ Python.
- قاعدة بيانات (اختياري): SQLite لبدء التشغيل السريع محليًا، Postgres للاستخدام على مستوى الفريق/الاختبار المرحلي.
- واجهة سطر الأوامر (Terminal shell): PowerShell (Windows)، zsh/bash (macOS/Linux).
التحقق من أدواتك
bash git --version node -v npm -v python3 --version pip --version
إذا كانت وثائق مشروعك تحدد إصدارات دقيقة، فقم بتثبيتها الآن. يعد انحراف الإصدار هو السبب الأول لفشل التثبيت الذي يظهر رسالة "يعمل على جهازي".
تثبيت OpenClaw على macOS/Linux
على نظامي macOS أو Linux، قم بتشغيل المثبت الموحد:
curl -fsSL https://openclaw.ai/install.sh | bash
لطرق التثبيت البديلة والمتطلبات التفصيلية للنظام، راجع قسم التثبيت.
1. تشغيل معالج الإعداد (Onboarding Wizard)
openclaw onboard --install-daemon
يقوم هذا المعالج بإعداد المصادقة، وتكوين البوابة، وأي قنوات مراسلة اختيارية (واتساب، تيليجرام، إلخ).
للحصول على شرح كامل، ارجع إلى وثائق معالج الإعداد.
2. التحقق من البوابة
إذا قمت بتثبيت خدمة الخلفية (الخفي)، فيجب أن تكون قيد التشغيل بالفعل. تحقق من حالتها باستخدام:
openclaw gateway status
3. فتح واجهة المستخدم للتحكم
إطلاق لوحة التحكم:
openclaw dashboard
يمكنك الآن الوصول إلى مثيل OpenClaw الخاص بك من خلال واجهة المستخدم للتحكم القائمة على المتصفح.
تثبيت OpenClaw على Windows
على Windows (باستخدام PowerShell)، قم بتشغيل المثبت الموحد:
iwr -useb https://openclaw.ai/install.ps1 | iexلطرق التثبيت البديلة والمتطلبات التفصيلية للنظام، راجع قسم التثبيت.
1. تشغيل معالج الإعداد (Onboarding Wizard)
openclaw onboard --install-daemon
يقوم هذا المعالج بإعداد المصادقة، وتكوين البوابة، وأي قنوات مراسلة اختيارية (واتساب، تيليجرام، إلخ).
للحصول على شرح كامل، ارجع إلى وثائق معالج الإعداد.
2. التحقق من البوابة
إذا قمت بتثبيت خدمة الخلفية (الخفي)، فيجب أن تكون قيد التشغيل بالفعل. تحقق من حالتها باستخدام:
openclaw gateway status
3. فتح واجهة المستخدم للتحكم
إطلاق لوحة التحكم:
openclaw dashboard
يمكنك الآن الوصول إلى مثيل OpenClaw الخاص بك من خلال واجهة المستخدم للتحكم القائمة على المتصفح.
التثبيت المعتمد على Docker (موصى به للاتساق)
إذا كنت ترغب في تقليل مشكلات التبعية على مستوى المضيف، قم بتشغيل OpenClaw باستخدام Docker Compose.
مثال على نمط docker-compose.yml:
yaml version: '3.9' services: app: build: . ports: - "3000:3000" env_file: - .env depends_on: - db - redis
db: image: postgres:15 environment: POSTGRES_USER: openclaw POSTGRES_PASSWORD: openclaw POSTGRES_DB: openclaw ports: - "5432:5432"
redis: image: redis:7 ports: - "6379:6379"
للبدء:
bash docker compose up --build
يوفر هذا النهج بيئات قابلة للتكرار عبر macOS و Windows و Linux، خاصة للفرق.
أخطاء التثبيت الشائعة وإصلاحاتها
1) أخطاء MODULE_NOT_FOUND أو الاستيراد
السبب: التبعيات غير مثبتة، ملف قفل خاطئ، أو وقت تشغيل غير متوافق.
الإصلاح:
- قم بإزالة
node_modulesوأعد التثبيت باستخدامnpm ci. - طابق وقت التشغيل مع وثائق المشروع (
.nvmrc,pyproject.toml,runtime.txt). - لا تخلط بين مديري الحزم إلا إذا كان المستودع يدعم ذلك.
2) رفض اتصال قاعدة البيانات
السبب: خدمة قاعدة البيانات معطلة أو DATABASE_URL خاطئ.
الإصلاح:
- تأكيد حالة الخدمة (
systemctl status postgresql,brew services list). - التحقق من صحة المضيف/المنفذ/المستخدم/كلمة المرور/اسم قاعدة البيانات.
- اختبار الاتصال بشكل مستقل باستخدام
psql.
3) المنفذ مستخدم بالفعل
الإصلاح: ابحث عن العملية المتعارضة وأوقفها.
macOS/Linux:
bash lsof -i :3000 kill -9
Windows:
powershell netstat -ano | findstr :3000 taskkill /PID /F
4) رفض الإذن على Linux/macOS
السبب: يفتقر النص البرمجي إلى إذن التنفيذ.
bash chmod +x ./scripts/*.sh
تجنب تشغيل أوامر التطبيق باستخدام sudo ما لم يكن ذلك ضروريًا للغاية.
5) لم يتم تحميل متغير البيئة
الإصلاح:
- تأكد من وجود
.envفي جذر المشروع. - أعد تشغيل العملية بعد تغيير
.env. - تحقق من تهيئة حزمة التحميل (
dotenv) في وقت مبكر.
قائمة التحقق من تعزيز الأمان بعد التثبيت
بمجرد أن يبدأ OpenClaw بنجاح، قم بهذه الإجراءات قبل المشاركة مع زملائك في الفريق:
- تغيير الأسرار الافتراضية.
- فرض رموز API قوية.
- تقييد عناوين URL لـ CORS وعناوين URL للاتصال العكسي (callback URLs).
- تعيين مستويات تسجيل آمنة للإنتاج.
- إضافة فحص الصحة/الاستعداد.
- تكوين استراتيجية النسخ الاحتياطي لوحدات تخزين قاعدة البيانات.
إذا قمت بتعريضه خارج localhost، فضعه خلف وكيل عكسي (Nginx/Caddy) مع TLS.
التحقق واختبار واجهات برمجة تطبيقات OpenClaw بسرعة
بعد التثبيت، يجب عليك التحقق من سلوك نقطة النهاية – وليس فقط بدء العملية.
نمط سريع:
- استيراد ملف OpenAPI الخاص بـ OpenClaw (إذا تم توفيره).
- إنشاء متغيرات بيئة لعناوين URL المحلية/المرحلية.
- بناء فحوصات تراجع للمصادقة، CRUD، ونقاط نهاية webhook.
هذا هو المكان الذي يساعد فيه Apidog في تقليل الاحتكاك. يمكنك تصميم، تصحيح، اختبار، وتوثيق واجهات برمجة التطبيقات في مساحة عمل واحدة، بحيث لا ينتشر التحقق من الإعداد عبر أدوات متعددة.
سير عمل عملي في Apidog:
- استيراد المخطط وإنشاء مجموعات طلبات.
- إضافة اختبار آلي مع تأكيدات قائمة على السيناريو.
- محاكاة التبعيات المفقودة باستجابات ديناميكية.
- مشاركة الوثائق التفاعلية مع فريقك بمجرد استقرارها.
إذا كنت تختبر نسخ OpenClaw ذات التغييرات المتكررة، فإن سير العمل الفردي هذا أسرع من الصيانة اليدوية للنصوص البرمجية بالإضافة إلى الوثائق المنفصلة.
استراتيجية الترقية لنسخ OpenClaw
تتطور نسخ الروبوتات/الأدوات مفتوحة المصدر بسرعة. استخدم مسار تحديث قابل للتكرار:
bash git fetch origin git checkout main git pull npm ci npm run migrate npm test npm run dev
لبناءات Python:
bash pip install -r requirements.txt python manage.py migrate pytest
استخدم الاختبار القائم على الفروع قبل دمج التغييرات من المصدر. إذا كان فريقك يستخدم عقود API، فإن فحوصات اختلاف المخطط تمنع التغييرات الجذرية الصامتة.
أفكار أخيرة
تثبيت OpenClaw (Moltbot/Clawdbot) على macOS، Windows، أو Linux أمر بسيط بمجرد التحكم في ثلاثة متغيرات: إصدار وقت التشغيل، تكوين البيئة، وتبعيات الخدمة.
إذا كنت تقوم بالتثبيت لفريق، فإن Docker Compose عادة ما يكون الأساس الأكثر موثوقية. إذا كنت تقوم بالتثبيت للتطوير المحلي، فإن الإعداد الأصلي جيد – فقط قم بتثبيت الإصدارات ووافق على نصوص الإعداد.
بمجرد تشغيل OpenClaw، عامل التحقق من API كجزء من التثبيت المنجز بشكل صحيح. يمكنك استيراد واختبار نقاط النهاية في Apidog، وإنشاء فحوصات آلية، ومزامنة الوثائق مع تطور نسختك.
جربه مجانًا—لا توجد بطاقة ائتمان مطلوبة—واستخدمه لتأمين سير عمل OpenClaw API الخاص بك من التشغيل الأول إلى اختبار التراجع.